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About this Manual 


The LightShip User’s Guide describes how to build a 
LightShip™ application. This manual is organized mainly by 
task. Use it to get acquainted with LightShip and then refer to 
it as you work. Use the LightShip Reference Guide to look up 
commands, actions, and functions. 


Read Chapter 1: Getting Started to find out how to install and 
start LightShip. Then run through the on-line demonstrations 
and work through the tutorial, Learning LightShip. 


This manual assumes that you are familiar with your computer, 
know how to use a mouse, and have some familiarity with 
Microsoft® Windows™. It is organized as follows: 


= Chapter 1: Getting Started explains how to start the pro- 
gram. It also shows you some basic things about using 
LightShip. 


= Chapter 2: Applications, Screens and Files explains how 
to work with files and create application screen 
backgrounds. 


= Chapter 3: Objects, Tools, and Modes describes the tools 
and objects you use to display information and the 
different modes that are available to work in. It also 
covers general information that applies to all objects, such 
as creating and editing. The following chapters describe 
how to create each object in detail. 


= Chapter 4: Displaying Data explains how to display and 


format data on a LightShip screen. It also explains how to 
color variances in the data. 


xi 


LightShip User’s Guide 


Chapter 5: Text, Draw Objects, and Images explains how 
to enter text for screen headers and labels; create draw 
objects, such as rectangles and polygons; and display 
images, such as Clipboard, PCX, or BMP files. 


Chapter 6: Creating Charts explains how to create graphs 
of data. 


Chapter 7: Creating Menu Objects explains how to create 
menu-bar menus and special hidden menu objects. 


Chapter 8: Creating HotSpots describes how to create 
buttons that perform actions. 


Chapter 9: Defining Actions describes how to define 
actions and functions. 


Chapter 10: Using Variables and Parameters explains 
how to store values in variables, assign new values while 
the program is running, and pass information between 
LightShip files. 


Chapter 11: Running and Testing an Application explains 
how to run and debug your application. 


Chapter 12: Using Dynamic Data Exchange (DDE) 
describes how to use DDE to exchange information with 
other Windows applications. 


About this Manual 


ZS Shortcuts are 
shown in a notebox Conventions Used in this Manual 


in the margin. 


We use some standard formatting conventions in this manual 
to help you learn to use LightShip more quickly. 


= Menu commands usually follow the menu name they are 
on. For example: 


1. Choose File Open. 
means "choose the Open command on the File menu.’ 


= A task that is about to be described is shown in bold 
characters next to a shadowed purple square (@). 
Procedures are shown as numbered steps. Choices or 
parts of a numbered step are shown next toa small purple 


square (m) 
= Examples are shown in bold monospaced characters. 


= Names that you need to substitute are shown in angle 
brackets (<>). For example: 


<pathname> 


means "type in the drive and directory appropriate for 
your site." 


= Key names are spelled out in capital letters. A plus sign 
(+) between two key names indicates that you must press 
both keys at once. For example: 


1. Press ALT+F. 


indicates that you should hold down the ALT key and press 
the F key. A slash (/) between two keys means you can 
press either one or the other. For example, UP/DOWN 
means you can use the uP or the DOWN arrow keys. 
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= The DIRECTION keys are the four arrows on your computer’s 
keypad. The name of the key refers to the direction in 
which the arrow points: the up key, the DOWN key, the RIGHT 
key, or the LEFT key. 


= New terms, action names, variable names, and book titles 
are italicized. 


= Because the Capture level is a limited version of the 


Browse level, most references to the Browse level are also 
meant to include the Capture level. 


IF Important Important information, notes, and performance hints are 
shown next to a hand to make them stand out. 


What You Need to 
Use LightShip 


Chapter 1 
Getting Started 


Pilot™ LightShip is an object-oriented application 
development package for creating Executive Information 
Systems (EIS). An EIS provides access to the latest corporate, 
departmental, and external data. LightShip allows you to build 
an EIS application in less time than ever before, without 
writing any code. 


This chapter shows you how to start the program, use the 
menu bar, manipulate the window, and get on-line help. 


Before You Start 


Besides this manual, your LightShip package should include: 


a LightShip Reference Guide 
a Learning LightShip tutorial 
s LightShip program disks 1 and 2 


To run LightShip you need the following: 


= A personal computer with an Intel® 80286, 80386, or 
higher processor. We recommend a 386-class computer or 


higher. 
a» DOS 3.1 or higher. 


= Microsoft Windows version 3.0 or higher. LightShip does 
not support Windows real mode. 
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= Aminimum of 2 megabytes of memory. We recommend at 
least 4 megabytes of memory. 


= About 5 megabytes of disk space if you install all the files. 
About 1 megabyte of disk space if you do not install the 
demonstration files. We recommend using a hard disk 
with at least 80 megabytes of disk space. 


= Color EGA, VGA, 8514/A or Hercules® graphics card, or 
compatible video graphics adapter and appropriate 
monitor. We recommend a VGA or other Windows- 
compatible graphics card. 


= A Microsoft Mouse or compatible pointing device. 
Compatible LightShip can display ASCII text files and data from other 
Software Windows 3.0 applications that use DDE. LightShip can also 


display graphic images copied from the Windows Clipboard or 
from files in PCX or BMP format. 


Installing LightShip 

LightShip expects you to install the program from your A drive 
at the DOS command line. If you install LightShip from your 
B drive, type: 

assign a = b 


before starting the installation procedure. 


@ To install LightShip, insert the LightShip program 
disk 1 into your A drive and type: 


az:install 


The installation procedure prompts you for the 
information it needs. 
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Starting LightShip 
from Windows 


Chapter 1 Getting Started 


If you have problems or questions, call the Pilot Technical 
Support Hotline (617) 338-HELP. 


Starting LightShip 


You can start LightShip from Windows or the DOS command 
line. 


@ To start LightShip from Windows: 

1. Start the Windows File Manager. 

2. Select the LightShip drive and directory. 
3. Double-click on the file LS.EXE. 


@ To start LightShip and optionally specify a file to 
open: 


1. Choose File Run from the Program Manager or the File 
Manager. 


2. Type the command to start LightShip, optionally followed 
by a filename. 


When you specify a filename, LightShip opens that screen. 
For example, to open the ADVAN.LSF file in C:\DEMO, you 


would type: 
7 INTERNAL. 
c:\ls\ls.exe c:\demo\advan.1sf 


You must specify the pathname of the LightShip program 
if it is not defined by your DOS PATH command. If you 
use the File Manager Run command, you must also specify 
the pathname of the file. You do not need to type the file 
extensions (.EXE and .LSF). 
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Displaying the 
LightShip Icon 


Li 


To display the LightShip icon: 


Select the program group in which you want to put the 
icon. 


Choose File New. 

The New Program Object dialog box appears. 

Select New Program Item. 

Choose OK. 

The Program Item Properties dialog box appears. 

In the Description text box, type: 

LightShip 

Type the command to start LightShip in the Command 
Line text box. For example, if LightShip is in C:\LS, you 
would type: 

c:\ls\ls.exe 


Choose OK. 


The icon appears in the program group window you 
selected. 


To start LightShip from the icon: 


Double-click on it. 
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Starting LightShip @ To start LightShip from the DOS command line: 
from DOS 
Type the command to start Windows, followed by the 
command to start LightShip (optionally followed by a 
filename). For example: 


win c:\ls\ls c:\demo\advan.l1sf 


Starting LightShip All the methods described previously start LightShip at the 

at the Browse Author level, which you use to develop applications. There are 

Level two other levels from which you run applications, Browse and 
Capture. The Browse level allows access to Windows, while 
Capture does not. 


@ To start LightShip at the Browse level without access 
to the Author level: 


Type the command to start LightShip followed by the /b 
argument and a filename. For example: 


c:\ls\ls /b c:\demo\advan.lsf 


D> press F4 to @ To start at the Browse level and allow access to the 


Author level: 
move between 


Author and Browse 


Type the command to start LightShip followed by the /ab 


levels. 
veS argument and a filename. For example: 


c:\ls\ls /ab c:\demo\advan.isf 
@ To start LightShip at the Capture level: 


Type the command to start LightShip followed by the /c 
argument and a filename: 


c:\ls\ls /c c:\demo\advan.lisf 
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Control-Menu Box 
Menu Bar 


The LightShip Window 


When you start LightShip, a new, blank screen appears in the 
window unless you specified a file to open as an argument on 
the command line. Figure 1-1 shows LightShip when you first 
Start it at the Author level. 


Title Bar Window i Minimize Button Maximize Button 


LightShip - Untitled 
File Edh Options View Special Tool 


Figure 1-1 The LightShip Window 


The menu bar contains the names of the LightShip menus and 
the Control menu. The Control menu contains commands to 
resize, move, maximize, minimize, close the LightShip 
window, and switch to the Task List. Display it by clicking on 
the Control-menu box above the File menu or by pressing 
ALT+SPACEBAR. 


All of the features of the LightShip window are standard Win- 
dows features. For complete information about how to use 
Windows, see the Microsoft Windows User’s Guide. 
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Choosing Menu Commands 
@ To choose a menu command with the mouse: 
1. Click on the menu name. 
The menu appears on the screen. 
2. Click on the command. 
@ To choose a menu command using the keyboard: 


1. Press the ALT key and the underlined letter of the menu 
name. For example, ALT+F displays the File menu. 


The menu appears on the screen. 
2. Press the underlined letter of the command. 


For example, you can press the o key when the File menu 
appears to make the File Open dialog box appear. 


@ To issue a command without displaying the menu: 


Press the shortcut key(s) shown next to the command on 
the menu. 


For example, press the Fs key to execute the File Open 
command. 


Menu Conventions 


A dimmed menu command means the command is not 
available at this time. For example, if nothing is on the 
Clipboard, you cannot choose the Edit Paste command. 


Copy Ctritins 


Clear  Shift+Del 
Duplicate Ins 
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Outline > 


V Show Hidden Objects 
Disable Formats 

Grid... 

Status Box 


A check mark next to a menu command means the command 
is on. To turn the command off, choose it again. For example, 
when Show Hidden Objects is on, all objects on the screen are 
outlined. 


A menu command followed by ellipses (...) means a dialog box 
or another screen will appear, asking you for more 
information. 


A triangle at the right side of a menu command leads to a 
cascading menu, which lists additional commands. For 
example, the Outline command leads to the menu shown in 
Figure 1-2. 


LightShip - Untitled 


Outline Hotspots h 


Show Hidden Objects |v Alt Objects 
Disable Formats 

Grid... 

Status Box 


Figure 1-2 A Cascading Menu 


@ To display a cascading menu with the mouse: 


Click on the menu item next to the triangle. 
@ To display a cascading menu with the keyboard: 


Position the cursor on the menu item next to the triangle 
and press RIGHT ARROW or ENTER. 
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Using a Dialog Box 


LightShip displays a dialog box when it needs more informa- 
tion. A typical dialog box is shown in Figure 1-3. 


Command Buttons 


Drop-Down List Box Variables 
Name: mn 
Text Box EE 


Name = Value List: 
Ricalcdwr - e \ls\demo\examples 
ttdatadi = e:\is\demo\data 
excel = e:\excel\excel exe 
&kisdir = e:\is 


~ e:\qe\qe.exe iii 
ttwindi = e: \win30 


List Box 


Check Boxes 


Figure 1-3 A Dialog Box 


Using Buttons A command button, also called a push button, is a round- 

cornered button labelled with the action that it carries out. 

Command buttons initiate an immediate action. 

@ To carry out a command and close a dialog box: 
Choose the OK button or press ENTER. 

@ To cancel a command and close a dialog box: 
Choose the Cancel button or press ESC. 

A check box is an option that can be turned on or off. An X 

appears in the box when the option is turned on; when it is 

off, it is blank. 


@ To turn a check box on or off: 


Click in it. 
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There is another button type not shown in Figure 1-3. These 


are option buttons. These buttons exist in groups and only 


one can be on at a time. When an option button is on, it turns 


black. 


The Chart Type dialog box, shown in Figure 1-4, shows a 
group of option buttons. 


Chart Type 
Series 


Option Buttons 


L] Horizontal 
es E E Arung ik 5 Bo [_] $ AFTA $o oA : 
% Width: C] es ggg i iagisr 


“eevee 


Figure 1-4 Option Buttons 


@ To turn a check box on or off: 


Click in it. 


Using Text Boxes A text box is a rectangle into which you type information. 


When you open a dialog box, if there is text in a text box, it is 


usually selected and any text you type replaces it. 
© To edit text: 


Click in the text box at the insertion point. 


The cursor changes to a flashing vertical bar. The text you 


type begins at the insertion point. 
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Using Drop-Down 
List Boxes 


Using List Boxes 


OS A quick way to 
choose an item 
from a list is to 


double-click on it. 
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@ To type into an empty text box: 
Click in it and type. 


For more information on editing keys, see "Editing Text in a 
Text Box." 


Drop-down list boxes display a list when you click on the 
arrow. You can then select an item from the list by clicking on 
it. Your selection is displayed in the text box next to the drop- 
down list box. 


Figure 1-5 shows the list that appears when you click on the 
drop-down list box in the Variables dialog box. 


Figure 1-5 A Drop-Down List 


A list box displays available choices for the command. You can 
scroll through the list by clicking the down arrow or by 
pressing ALT+DOWN ARROW. 


© To select an item from a list: 
Click on the item and then choose the command button 


you want. Or double-click on the item to choose it and 
complete the command. 
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Editing Text ina 
Text Box 


Using the Keyboard in a Dialog Box 


Use the following keys to move around and select options: 


ALT +underlined letter 


ENTER 


ESCAPE 


KEYBOARD LETTER 


TAB 


SHIFT+TAB 


UP/DOWN ARROWS 


PGUP/PGDN 


SPACEBAR 


Moves to the option with the under- 
lined letter. 


Carries out the command and closes 
the dialog box; it is the same as 
choosing OK. 


Cancels the operation and closes the 
dialog box. 


When a list box is selected, moves to 
the first item starting with that letter. 
Then it cycles through the items 
starting with that letter. 


Moves to the next option; for exam- 
ple, the next button or text box. 


Moves to the previous option. 


Scrolls through a list box one item at 
a time. 


Scrolls through a list box several 
items at a time. 


Acts like the mouse on the selected 
option; for example, it turns a check 
box on and off. 


Use the following keys to edit text in a text box: 


BACKSPACE 


Moves back one space and erases the 
character to the left of the cursor. 
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DEL Erases the character to the right of 
the cursor. 

RIGHT/LEFT ARROW Moves to the right or left in the line. 

HOME Moves to the beginning of the line. 

SHIFT +UP Selects the previous line. 

SHIFT+END Selects from the current position to 


the end of the line. 
SHIFT +HOME Selects to the beginning of the line. 
SHIFT+LEFT/RIGHT ARROW Selects text to the left or right of the 


insertion point as you press the LEFT 
Or RIGHT ARROW key. 


SHIFT +DOWN Selects the next line. 

SPACE Erases all text in a text box if you 
press it before typing. 

END Moves to the end of the line. 

Resizing the Window 


If the window is maximized, the Maximize box in the upper- 
right corner shows two black arrows; you cannot resize the 
window until you click the Maximize box or choose Control 
Restore. 


@ To resize the LightShip window with the mouse: 
1. Drag the window border. 


The cursor changes to a two-headed arrow that points in 
the direction in which you can drag the window. As you 
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drag the border, you will see a shadow border that 
indicates the size of the window. 


2. Release the mouse when the window is the size you want. 
@ To resize the LightShip window with the keyboard: 
1. Choose Control Size. 


A shadow border outlines the window and a four-headed 
arrow appears in the middle of the window. 


2. Use the DIRECTION keys to indicate the direction in which 
you want to increase or decrease the size of the window. 


The shadow border indicates the new size of the window. 
3. Press the ENTER key when the window is the size you want. 


Maximizing the @ To increase the window to its maximum size: 


Window 
Click on the Maximize box or choose Control Maximize. 


Minimizing the @ To reduce LightShip to an icon: 


Window 
Click on the Minimize box or choose Control Minimize. 


@ To open the minimized LightShip program: 
Double-click on the icon. 


Restoring the @ To restore the window to its previous size: 


Window 
Choose Control Restore. If the window is maximized, 


click in the box in the upper-right corner. 
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Moving the Window 
@ To move the window with the mouse: 
1. Position the pointer on the title bar and drag the window. 


2. Release the mouse when the window is placed where you 
want it. 


@ To move the window with the keyboard: 
1. Choose Control Move. 


2. Use the DIRECTION keys to indicate the direction in which 
you want to move the window. 


3. Press the ENTER key when the window is where you want 
it. 


Setting Preferences 


You can specify certain system settings by choosing View 
Preferences. This opens the Preferences dialog box, shown in 
Figure 1-6. These settings, which allow you to customize 
LightShip’s performance, are automatically saved in your 
LS.INI file if you turn on Save Prefs. on Exit. You can also turn 
on Query Save on Exit so that LightShip asks you if you want 
to save the settings when you exit. 


For more information about the options in the Preferences 
dialog box, see the LightShip Reference Guide. For more 
information about LS.INI, see Appendix B: LS.INI Options. 
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Preferences 


Misc. Settings Exit Options 

EK) Display Startup Banner ÈI Query Save on Exit 
C] Direct Browse Level Painting ÈJ Save Prefs. on Exit 
pg Redraw During Move/Resize DJ Save Globals 

C] Print Screen as a Bitmap 

ÈJ Create *.BAK Files 


‘Not Available’ Values 
DDE NA - Incoming Values 
DDE Short Timeout 


QUTNA - Outgoing Value 
DDE Long Timeout = 


Default Hotspot Cursor Filename: 


Figure 1-6 Setting System Preferences 


Using Help 

The Help menu is a quick way to look up on-line information 
about commands. LightShip Help works very much like 
Windows Help. 


If this is the first time you have used on-line Help, choose 
Using Help from the Help menu to learn how to use it. 


@ To get help: 
1. Choose Help on the menu bar or press ALT+H. 


2. Choose the Help category you want or press the under- 
lined letter of the category. 


Or press DOWN ARROW or UP ARROW to reach the Help 
category you want and then press ENTER. 


A list of the items in the category appears. 
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3. Choose the item you want to know more about. 


Quitting LightShip 

@ To quit LightShip: 
Choose File Exit or Control Close. 
If you have made changes to the screen that you have not 
saved to a file, a dialog box asks if you want to save the 
changes. 
= Choose Yes to exit and to save the file. 


= Choose Noto exit and not save the file. 


= Choose Cancel to cancel the Exit. 
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Applications, Screens, and Files 


This chapter introduces the components of an application and 
describes how to create screen backgrounds and work with 
files. 


Overview of an Application 


You use the following components to build a LightShip 
application: 


= Screens 

a Objects 

m Actions 

= Variables 

= A database or spreadsheet application 


LightShip applications usually consist of a series of data-driven 
screens that are dynamically linked. You can navigate through 
the data by clicking on hotspots and menu items. 


You begin to build an application by creating a screen. You 
then create objects and place them on each screen the way you 
want them to appear in the application. These objects can 
display data or images, or they can define menus or hotspots, 
which contain actions. 
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Saving a Window 
Position and Size 


If you have no user-defined menus, you can completely hide 
the menu bar by turning on View Hide Menu Bar. If you have 
user-defined menus, turning on View Hide Menu Bar hides the 
LightShip Browse menus and displays the user-defined menus 
only. 


For more information about creating menus, see Chapter 7: 
Creating Menu Objects. 


Adding and Hiding Scroll Bars 


You can add scroll bars on any window for which there is 
information that needs scrolling. You can also hide scroll 
bars. Scroll bars are closely associated with document objects. 
For more information about adding and hiding scroll bars, see 
Chapter 4: Displaying Data. 


Saving a Window Position and Size 


You can save a window position and size so that your screen 
always displays as it was last saved to the file. If your 
application uses multiple screens, set the size and position for 
the first screen. Then choose Save Window Position for that 
screen, but not for subsequent screens. The called screens 
open with the same window position and size, which makes 
screen repainting faster and more visually pleasing. 


@ To save a window position and size: 


1. Position and size the window by dragging it with the 
mouse or using the Control Size command. 


2. Choose Options Save Window Position. 


Passing Local 
Variables 


Returning to an 
Instance of a 
Screen 
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Top Screen opens Screen 1 with an 
Open File - Add to Retrace Path action. 


Top Screen 


Screen 1 opens Screen 2 with an Open 
File - Replace in Retrace action. 


Screen 2 Screen 2 opens Screen 3 with an Open 
File - Add to Retrace Path action. 


Screen 3 opens Screen 4 with an Open 
File - Clear the Retrace Path action. 


Figure 2-10 Return in Retrace Path Actions 


Local variables are deleted any time you open another screen. 
Keep in mind that this occurs when you perform a Return in 
Retrace Path action, so if you want to preserve local variables, 
you must explicitly pass them by typing them in the Action 
Parameters dialog box. 


You can save the current state of a screen and reserve a place 
in the retrace path list for that screen by saving it with the Save 
File - Temporary Name action. If you then open another 
screen with Open File - Add to Retrace Path, a Return in 
Retrace Path from the called screen opens the temporary file. 
Temporary files are deleted when you leave LightShip. 
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Saving a Screen 
with a New Name 


Saving a Screen 
as a Temporary 
File 


LightShip updates the list of files to display the files in the 
selected drive and directory. 


2. Type in the filename or double-click on a file in the list. 


LightShip provides a default extension of .LSF. This 
extension is recommended but not required. 


3. Choose OK. 


@ To save an existing screen with a different name than 
the original file: 


Choose File Save As or press SHIFT+F9. 


The File Save As dialog box appears and prompts you for a 
filename (see Figure 2-5). The name last given to the file 
is displayed in the Filename text box. 


1. Type the filename or choose a filename in the list. 


2. Choose OK. 


You can save the current state of a screen by saving it with the 
Save File - Temporary Name action. Temporary screens are 
deleted when you leave LightShip. 


Saving a temporary file reserves a place in the retrace path. 
After saving a screen as a temporary file, if you open a screen 
with an Open File - Add to Retrace Path action, a Return in 
Retrace Path action from the called screen returns to the 
temporary screen. 


For more information on the Save File - Temporary Name 
action, see the LightShip Reference Guide. 
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The LightShip LightShip provides two variables that you define within a 
PATH Variables LightShip application to store a search path: 


= &PATH a local variable 


USS To initialize a = &&PATH a global variable 


global variable every 


ti tart 
a g nm > @ To define a PATH variable: 
LightShip, define it 


in LS.INI. For more i n 
1. Choose Special Variables or press SHIFT+F4. 
information about 


LS.INI options, see ; 
P A dialog box appears. 
Appendix B. 


Name: 
G 


Name = Value List: 


Figure 2-11 Defining a LightShip Path Variable 
2. Type the variable name in the Name text box. 
3. Type the search path in the Value text box. For example: 
c: \ls;c:\ls\demo;c:\ls\tutorial 

4. Choose OK. 
The LightShip The LIGHTSHIP DOS environment variable is a local variable 
DOS Environment you define at the DOS command line to store a LightShip 
Variable search path. 


@ To define this variable, type: 


set lightship = <pathlist> 
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Creating 
DEFAULT.LSF 


Editing 
DEFAULT.LSF 


Multiple 
Templates 


2-10 


Note that you can also set defaults for objects in DEFAULT.LSF. 
For example, if you want all text objects to default to a blue 
background with yellow text, you can assign this in 
DEFAULT.LSF. For more information about assigning 
attributes to objects, see Chapter 3: Objects, Tools, and Modes. 


J: 


To create a default screen template: 

Choose File New. 

Assign the defaults for the screen. 

To assign defaults to objects, choose the object type from 
the Tool menu and choose the menu items that you want 


as defaults. 


For more information about defining a specific object, see 
the chapter about that object type. 


Choose File Save As and type the pathname and filename. 
For example: 


c:\ls\default.1sf 


Choose OK. 


You can edit DEFAULT.LSF at any time just like any other 
screen. 


You can only have one DEFAULT.LSF file, but you can use any 
screen as a template. Just open that screen and then save it 
with a new name. 
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Figure 2-1 A LightShip Screen 


Coloring a Screen Background 
© To color a screen background: 
1. Choose Options Screen Color. 


A dialog box appears. 


Screen Color 


+." « . . . 
. . . _* . . 
DOR * . DOC : 
« ee . . 
. .* è . 


Figure 2-2 Coloring the Screen Background 


2. Selecta color. 


2-3 


LightShip User’s Guide 


Deleting a @ To delete a password: 
Password 
1. Choose Options Unprotect Author Level or Options 
Unprotect Browse Level. 


The Password dialog box appears. 
2. Type the password again. 


3. Choose OK. 


Printing a Screen 


You can print the screen displayed in the window. Before 
printing, make sure you have specified your printer settings. 
The printer settings stay in effect until you change them. 


Setting Up a © To set up a printer: 
Printer 
1. Choose File Printer Setup. 


A dialog box appears. All the printers installed in 
Windows display in the dialog box. Figure 2-7 shows the 
Printer dialog box. 


Printer 


Epson 9 pin on LPT1: 


Pcl }? HP LaserJet on LPT?2: 


Figure 2-7 The Printer Dialog Box 


2. Choose the printer that you want to set up. 
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You can also create a pop-up screen using the POSITION 
function. For more information, see Chapter 11 of the 
LightShip Reference Guide. 


Adding a Window Caption 

You can add a window caption that appears on the title bar of 
your application window at the Browse level. Window 
captions are also used in the Retrace Path dialog box. The 
window caption shown in Figure 2-4 appears on the screen in 
Figure 2-3. 

@ To add a window caption: 

1. Choose Options Window Caption. 


A dialog box appears. 


Window Caption 


LightShip to Excel Demonstration 


Figure 2-4 Adding a Browse Level Window Caption 
2. Type in the caption. 


4. Choose OK. 


Hiding the Menu Bar 


By default, a screen appears at the Browse level with a menu 
bar that displays the LightShip Browse menus (File, Edit, and 
Special). User-defined menus, if there are any, display on the 
menu bar to the right of the LightShip menus. 
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Opening a Screen 
File 


save screens in a particular state to which you want 
to return via the retrace path. For more information 
about temporary files, see page 2-19 of this chapter 
and Chapter 10 of the LightShip Reference Guide. 


Opening a Screen File 


When you open a file, LightShip displays a screen in the 
window. Opening a file automatically closes the screen 
currently displayed in the window. If you have made changes 
to the screen that you have not saved to a file, a dialog box 
asks if you want to save the changes. 


You open a file from the File Open dialog box as shown in 
Figure 2-8. All the .LSF files in the current directory are listed 
in the Files list box on the File Open dialog box. The current 
directory name appears above the list of files. All the 


subdirectories in the current directory are listed in the 
Directories box, followed by alternate drives, for example, 


[-a-], [-c-]. 
@ To open a screen file: 
1. Choose File Open or press Fs. 
The dialog box shown in Figure 2-8 appears. 
= To change drives: 
Choose the drive letter. 
= To change directories: 


Choose the subdirectory name or the symbol [..] to 
go to the next higher level directory. 


LightShip updates the list of files to display the files in 
the selected drive and directory. 
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Saving a Screen 

The first time you save a file, the File Save As dialog box opens 
and prompts you for a filename. All subsequent saves take 
place without the dialog box appearing. 

When you save a file, LightShip saves the previous version of 
the file with a .BAK extension, unless you turn off Create .BAK 
file in the Preferences dialog box. 


Saving a Screen © To save a screen: 


1. Choose File Save or press F9. 


Directory: e:\is\demo 


Directories: 


Figure 2-5 The File Save As Dialog Box 
© To change drives: 
Choose the drive letter. 
@ To change directories: 


Choose the subdirectory name or the symbol [..] to go to 
the next higher level directory. 


2-7 


LightShip User’s Guide 


2-16 


4. Choose OK. 


How One Screen Leads to Another 


When an application is running, a screen either leads to 
another screen or lets you exit from the application. The 
screen that opens another is the calling screen; the screen that 
is opened is the called screen. You call screens by creating 
hotspot or menu objects that perform an Open File action. 


The following actions open another screen: 


= Open File actions 
= Return in Retrace Path action 


The retrace path is an important part of these actions. 


What is the Retrace Path? 


LightShip keeps a list of all the files you open within a session, 
in the order in which you open them. This list is the retrace 
path. The retrace path allows you to find and open files easily 
and is most often used to return to a previous screen. The 
retrace path has a maximum of 32 entries. New entries are 
added to the end of the list, while entries from the beginning 
of the list are removed. For example, the 33rd entry is added 
to the end of the list and the first entry is removed, and so on. 


You can display the retrace path and choose a screen in the list 
to open it, or you can clear the list. Note that if you open a 
screen from this dialog box, it does not get added to the end 
of the retrace path list, but the retrace path list rebuilds from 
the screen you opened in the list. For example, if you opened 
Newstrack Top Menu from the Retrace Path dialog box shown 
in Figure 2-9 and then opened Newstrack National News, 
Newstrack National News would replace Newstrack Foreign 
News in the list. 
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Creating a New Screen 
@ To create a new screen: 
Choose File New or press SHIFT + F8. 


If you have made changes to the current screen that you 
have not saved to a file, a dialog box asks if you want to 
save the changes. 


= Choose Y for yes. 
= Choose N for no. 
= Choose Cancel to return to the screen. 


Creating a Default Screen Template 


You can create a default screen template by setting up a screen 
and saving it with the filename DEFAULT.LSF. The attributes 
you define in this file will appear on every new screen you 
create after that. You might want to create a default screen 
with a company logo and Return button, for example. 
DEFAULT.LSF must be in the current directory or defined in a 
search path. 


You can set the following screen attributes in the file 
DEFAULT.LSF: 


Boiler-plate objects 
Specific object attributes on the object menus 


= Screen color 

= Window size and position 
= Menu bar 

= # Scroll bars 

* 

a 


The attributes you set in DEFAULT.LSF can be changed on any 
screen once it is created. 
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of the retrace path list. This is useful if you want to return 
sequentially up through the calling screens. 


The Open File - Clear the Retrace Path action opens a file and 
erases all entries in the retrace path list except the first one. 
Use this if you want to return directly to the top screen from 
the screen being opened. 


The Open File - Replace in Retrace Path action opens a file and 
overwrites the calling filename with the called filename in the 
retrace path list. For example, in Figure 2-9, if Newstrack Top 
Menu had an Open File - Replace in Retrace Path action ona 
hotspot that opened Newstrack Foreign News, when 
Newstrack Foreign News opened, Newstrack Top would 
disappear from the retrace path. When Newstrack Foreign 
News executed a Return in Retrace Path, it would open the 
Demonstration Top Menu. 


The Return in A Return in Retrace Path action opens the file above itself in 
Retrace Path the list. For example, in the retrace path shown in Figure 2-9, 
Action if Newstrack Foreign News has a Return in Retrace Path action 


on a hotspot, it would open Newstrack Top Menu (assuming 
Newstrack Top Menu opened it with an Open File - Add to 
Retrace Path action). The retrace path is like a stack; the first 
one in is the last one out. 


Figure 2-10 shows how each Open File action opens a screen 
using Return in Retrace Path. A Return in Retrace Path action 
from the called screen opens the file indicated by the arrow. 


Defining a 
Password 
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Creating Passwords 


You can protect access to a screen by creating passwords for 
the Author and Browse levels. These passwords affect only the 
screen where you define them. When a screen is password- 
protected at the Author level, anytime you open it at that level, 
you are prompted to enter the password. When a screen is 
password-protected at the Browse level, you are not prompted 
for the password when you open it from the Author level; you 
are Only prompted when you open the screen at the Browse 
level. Be careful to remember the password, because the 
screen is unaccessible without it. 


Passwords can be up to 20 alphanumeric characters and are 
not case-sensitive. 
@ To define a password: 


1. Choose Options Protect Author Level or Options Protect 
Browse Level. 


A dialog box appears. 


Enter Password 


Figure 2-6 Defining a Password 


2. Type the password. 
It appears as asterisks. 
4. Choose OK. 
You are prompted to confirm the password. 


4. Type it again and choose OK. 
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The Search Path 
Check Box 


Defining a Search Path 


In general, we recommend keeping all files associated with an 
application in one directory, for example, screen, text, and 
graphic files. However, you still might open files and 
applications in a variety of directories. A search path specifies 
drives and directories where files are stored. To make pathing 
information easier to maintain, LightShip provides several 
ways of defining search paths. LightShip searches the drives 
and directories in the order in which they are listed in the 
search path. 


You can define a search path in a special local or global 
LightShip variable, a LightShip DOS environment variable, or 
you can use the DOS PATH command. All of these are 
described more fully below. 


Turn on the Search Path check box, found on most file dialog 
boxes, if you have one or more search paths defined. This tells 
LightShip to search the paths you’ve defined. We recommend 
using this option. If the Search Path check box is off, 
LightShip searches only the directory specified in the dialog 
box. 


When Search Path is on, LightShip searches for files in the 
current directory or in a search path you have defined. 
LightShip searches for files in the following order: 


Current working directory 

Path defined by the local LightShip variable, &PATH 
Path defined by the global LightShip variable, &&PATH 
Path defined by the LIGHTSHIP environment variable 
Path defined by the DOS PATH command 


we Ae Ey pa 
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3. Choose the Setup button. 
This opens a Windows dialog specific to the printer you 
selected. It prompts you to specify printing orientation, 
paper source and size, resolution, and other settings. 


4. Make your selections. 


5. Choose OK. 


Printing @ To print a screen: 
1. Open the screen. 


2. Choose File Print. 


LightShip Files 


There are four kinds of LightShip files, which are identified by 
their extensions: 


„LSF These are screen files. If you do not type an 
extension when saving a file, LightShip gives the file 
this extension. 


.BAK These are backups of screen files. When you save a 
file, LightShip saves the previous version of the file 
with a .BAK extension, unless you turn off Create 
.BAK file in the Preferences dialog box. 


.LOG This is an error log file to use when testing and 
debugging your application. For more information 
about this file, see Chapter 11: Running and Testing 
an Application. 


. TMP This is a temporary file created by a Save File - 
Temporary Name action. Use temporary files to 
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Actions control the operations that take place and how you 
navigate through the screens. Actions also allow you to build 
dynamic, data-driven queries depending on which hotspots 
you click on. LightShip actions include: 


Commands 

Functions 

Mathematical operations 
Logical operations 
Relational operations 


You display data in document objects. You can enter data 
manually, display text files, or display data from any 
application that uses DDE, including Microsoft Excel, 
Microsoft PowerPoint®, and Pioneer Q+E™. LightShip 
supports hotlinks to DDE applications, so data display is 
automatically updated when the data in the source changes. 


Application Screens 


You can open only one screen at a time in each instance of the 
LightShip program; however, you can run multiple instances 
of LightShip at a time. 


LightShip application screens have a title bar, Control menu, 
Maximize and Minimize buttons, and optionally, a menu bar 
and scroll bars. 


You can control the following attributes of a screen: 


Color 

Window caption in the title bar 
Position and size of the window 
Menu bar 

Scroll bars 
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Fin Open 
Filename: 


Directory: e:\is\demo 


Directories: 


toppop.lsf 


ÈJ Search Path 


Figure 2-8 Opening a File 
Type the filename or click on a filename in the list of files. 
m To list a specific subset of files: 
Substitute character(s) in the filename with an 
asterisk (*). For example, to list all the files that start 
with "ap" and end with ".Isf," type: 
ap*.1isf 


= To list all the files with extensions that start with 
"1," , type: 


*. 1% 


Turn on the Search Path option if you want LightShip to 
look for the file in the current working directory first, and 
then in a search path you have defined. 


If you do not turn on the Search Path option, LightShip 
searches only the directory specified on the dialog box. 
For more information, see "Defining a Search Path," later 
in this chapter. 
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3. Choose OK. 


LightShip allows as many colors as your display adapter 
supports. You can customize 48 of the colors on the palette by 
choosing Options Palette. For more information, see Chapter 
5: Text, Draw Objects, and Images. 


Creating a Pop-Up Screen 


You can use the Invisible option on the Options Screen Color 
dialog box to create a pop-up screen. For example, create a 
new screen with a small chart or a draw object that looks like a 
dialog box. Then give the screen an invisible screen color and 
save and close the file. 


When you call the screen with the invisible screen color, the 
calling screen appears behind the chart or draw object as a 
grayed background (see Figure 2-3). 


LightShip to Excel Demonstration 


Net Sales for All Divisions 


0 20000 40000 60000 80000 100000 120000 140000 160000 


Figure 2-3 Creating a Pop-up Screen 
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The retrace path usually displays window captions; if a screen 
has no window caption, it lists the filename. 


Displaying the ®@ To display the Retrace Path: 
Retrace Path 


Choose Special Retrace Path or press F10. 


A dialog box appears. 


Retrace Path 


| op a V mii 
Newstrack Top Menu c 


Newstrack Foreign News 


Figure 2-9 Displaying the Retrace Path 
Use this dialog box to: 


= Erase all entries in the retrace path (except the top entry) 
by clicking the Clear button. 


= Open a file in the retrace path by double-clicking on the 
filename. 


= View the retrace path and click Cancel to close the dialog 


box. 
The Open File There are five Open File actions; each one opens a file and 
Actions manipulates the retrace path. 


The Open File - Add to Retrace Path and the Open File - Dialog 
(Add to Retrace Path) actions open a file and add it to the end 
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where <pathlist> is a list of drives and directories, separated 
by a semicolon, that will be searched. 


The DOS PATH Use the DOS PATH command to define a search path at the 
Command DOS command line. 


@ The general form of this command is: 
PATH <pathlist> 


where <pathlist> is a list of drives and directories, separated 
by a semicolon, that will be searched. 
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Objects, Tools, and Modes 


This chapter introduces the objects, tools, and modes that you 
use to create an application. It also describes the operations 
that are common to all objects. Use the chapters that follow to 
learn how to work with each type of object individually. 


LightShip Objects 


You use objects to display data, images, menus, and buttons. 
Certain objects can also contain variable references and 
actions that are executed at the Browse level. 


o LightShi 
Menu Object tbl 


Image Object 443 re 1485 J F ID, 
Text Object liao Soles fopa ° 
: Actual Budget : Divisions 
| Censolidated : 
J Sales “4 : Electric 
Jj Chamical $35,824 $45,800 “4d Chemical 
| Electric $35.955 $33.000 f] : Consolidated 
Document and Hotspot | Paper $27.783 $20.000 È] : Paper 
Objects q torn Sales $99.562 $98.000 : 
Chart Object 
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Selecting Multiple 
Objects 


You can select multiple objects and perform operations on all 
of them at once. This is different from grouping objects, 
where multiple objects are treated as one object. The opera- 
tions you can perform on multiple objects are: 


Move, Cut, Copy, Paste, Duplicate, Clear 
Send to Back and Send Backward 
Bring to Front and Bring Forward 


To select objects that are next to each other with the 
mouse: 


Drag the mouse around the objects you want to select 
until they are completely enclosed. 


Make sure the cursor is not touching any object or you 
will move it. You will see a dotted selection rectangle as 
you drag the mouse. You must entirely enclose all the ob- 
jects you want to select within this rectangle. 


LightShip - Untitled 
File Edit Qptions View Special Tool 


Figure 3-6 Selecting Multiple Objects 


Pasting Objects 
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@ To copy the selected object(s) or group: 

1. Choose Edit Copy or press CTRL+INS. 

2. Click on the place where you want to paste the object. 
If you don’t click the mouse before choosing Paste, the 
copy appears below and to the right of the original object. 
You can then drag the new object to the desired location. 

3. Choose Edit Paste or press SHIFT+INS. 

@ To duplicate the selected object(s) or group: 


Choose Edit Duplicate or press INS. 


The copy appears overlapping the original object, slightly 
lower and to the right. 


4. Drag the copy away from the original. 

You use the Paste command to place a copy of an object that 

has been cut or copied to the Clipboard on the screen. You 

can only paste back the object that was last cut or copied to 
the Clipboard. 

@ To paste the selected object(s) or group: 

1. Click on the place where you want to paste the object. 
If you don’t click the mouse before choosing Paste, the 
object will appear a little below and to the right of the 
original. You can then drag the copy to the desired 
location. 


2. Choose Edit Paste or press SHIFT+INS. 


You can continue pasting the same object(s) until you cut 
or copy something else. 
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Image 


Source 

Scaling... 
Fit Object to Image 
Fit Image to Object 
Save Palette 


For All Objects of 
One Type 


Assigning Attributes to Objects 

Once you create an object, you define it further by assigning 
attributes to it. For example, an object’s size, color, and data 
source are attributes. The settings on the object menu de- 
termine the object’s attributes when it is created. 

@ To assign an attribute to an object: 

1. Select the object. 


The menu for that object type appears on the menu bar. 


2. Choose an item from the object’s menu. 


setting Defaults for Objects 


LightShip automatically sets defaults for both objects and 
screens. You can override these and set your own defaults by 
creating a file called DEFAULT.LSF. For information about 
how to create this file, see Chapter 2: Applications, Screens, 
and Files. 


The default settings on a menu are marked by a black diamond 
next to the menu item. If you create an object without chang- 
ing these settings, the object is created with the default 
attributes. 


You can change an object’s attributes either before or after you 
create it. If you change an attribute before creating an object, 
that setting becomes a default for all objects of that type for 
that screen. If you change an attribute after creating an object, 
the setting only changes for that specific object. 


@ To set defaults for an object type on a specific screen: 


1. Choose the object from the Tool menu. 


Displaying the 
Status Box 
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You can display information about the screen or a selected 
object or group using the Status box. If no object or more 
than one object is selected, the Status box displays the: 


= Cursor position 
= Current mode 
= Number of objects on the screen 


If one object or group is selected, the Status box displays the 
following additional information: 


= Object or group number. 

= Object or group position in pixels. The first number is the 
horizontal coordinate and the second number is the 
vertical coordinate. 

= Object or group width in pixels. 

= Object or group height in pixels. 


The object information is helpful when you use the POSITION 
function, which requires an object’s position and size. Figure 
3-11 shows how the Status box appears when an object is 
selected. 


@ To display the Status box: 


Choose View Status Box. 


status 
Cursor:96,64 Mode:Select Objects:33 


Obj.#:29 Pos.:252.79 Width:113 Height:32 
Figure 3-11 The Status Box 


@ To close the Status box: 


Choose View Status Box again or double-click on the title 
bar. 
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For information on how to view and list objects, see "Keeping 
Track of Objects." 


Grouping Objects 


You can group multiple objects together so that they are 
treated as one object until you ungroup them. You can per- 
form the following operations on grouped objects: 


Move 

Cut, Copy, Paste, Duplicate, Clear 
Send to Back and Send Backward 
Bring to Front and Bring Forward 


You cannot assign attributes to a group or resize it. When you 
select a group, no object menu appears on the menu bar. You 
must ungroup the objects and select them individually to 
specify attributes from an object menu. 

You can display information about individual objects in a 
group by listing them in the Debug window. For more 
information, see "Keeping Track of Objects." 

@ To group objects: 


1. Select all the objects that you want to group by dragging 
the mouse around them. 


2. Choose Special Group. 
@ To ungroup grouped objects: 
1. Select the group. 


2. Choose Special Ungroup. 


Select Mode 


R 


Point Mode 


f 


Getting to Point 
Mode 


The Point Mode 
Screen 


Chapter 3 Objects, Tools, and Modes 


Use Select mode to select an object before you do something 
to it. 


@ To enter Select mode: 


1. Choose Tool Select or click on the Pointer icon in the 
Toolbox. The cursor changes to the pointer. 


N 


Click on an object to select it. 


Use Point mode to select data from document objects. For 
more information, see "Point Mode." 


Point Mode 
Use Point mode to select data from document objects to: 


Format a document 

Select data series’ and other information for charts 
Assign parameter values using the Point option 

Assign function arguments using the Point option 

Point to a different source document when coloring vari- 
ances 


The way you get to Point mode depends on the object you are 
defining. For example, if it is a format object, you choose 
Format Destination; if it is a chart object, you choose Chart 
Data and the number of the data series for which you want to 
select data. 


The Point mode screen appears similar to the one shown in 
Figure 3-12. You can point to items on the screen to select 
them. The title bar and menu bar change when you enter 
Point mode. The title bar tells you what you are selecting. For 
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= Choose Send to Back to move the selected item 
behind all other objects. 


= Choose Bring to Front to move the selected item in 
front of all other objects. 


Resizing an When you click on an object’s border, a perpendicular two- 

Object headed arrow appears, and you can drag the object’s border 
up and down. When you click on an object’s corner, a 
diagonal two-headed arrow appears, as shown in Figure 3-8. 
This cursor allows you to move the object’s border up and 
down, as well as left and right. 


@ To resize an object: 
1. Point to the object’s border or corner. 


2. When the cursor changes to a two-headed arrow, drag the 
object until it is the size you want. 


LightShip - Untitled 
File Edit Options View Special Tool Text 


Figure 3-8 Resizing an Object 
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How to Select @ To select data in Point mode: 
Data 
Drag the cursor over the items you want to select. 


@ If you make a mistake: 


= Choose Undo! to deselect the last column you 
selected. You can choose Undo! multiple times and it 
will deselect highlighted items in the order that you 
selected them (from the last selected to the first 
selected). 


= Choose Redo! to reselect the items that you 
deselected with Undo! in the order that you selected 
them (from first to last). 


= Choose Clear All! to deselect all the highlighted 
columns. 


@ To exit from the Point mode screen: 


Choose OK! to proceed, or Cancel! to exit and cancel 
what you selected. 
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Resetting the 
Default 


Erasing Objects 


Copying Objects 


5. Choose OK. 


@ To reset the grid back to the default of half an inch: 


Choose the Default button. 


Editing Objects 


Use the Edit menu to cut, copy, paste, clear, and duplicate 
objects. 


You can erase objects with the Cut or Clear commands. The 
Cut command erases an object, but saves it on the Clipboard 
so you can use the Paste command to bring the object back. 
Note that when you cut something, it overwrites whatever is 
currently on the Clipboard. The Clear command permanently 
erases an object, and it is not saved on the Clipboard. 


@ Tocut the selected object(s) or group: 


Choose Edit Cut or press DEL. 


To clear the selected object(s) or group: 


Choose Edit Clear or press SHIFT+DEL. 


You can copy object(s) with the Copy and Duplicate com- 
mands. The Copy command makes a copy of an object and 
saves it on the Clipboard. You can use the Paste command to 
bring the object back. Note that when you copy an object, it 
overwrites whatever is currently on the Clipboard. The 
Duplicate command copies and pastes the selected object(s) in 
one step. 


Chapter 3 Objects, Tools, and Modes 


The Toolbox 


The Toolbox displays the tools as icons. You use the Toolbox 
to create multiple objects quickly. When you select a tool 
icon, you create an object of that type every time you click or 
drag the mouse on the screen. 

The Toolbox first appears on the right side of the screen. To 
move it, point to the top of the Toolbox and drag it to the 
desired location. 

@ To open the Toolbox: 


Choose Tool Toolbox. 


Pointer 

Chart Tool 
Document Tool 
Draw Tool 
Format Tool 
Hotspot Tool 
Image Tool 
Menu Tool 


Text Tool 


@ To close the Toolbox: 


Double-click on the top of the Toolbox or choose Tool 
Toolbox again. 
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Listing Objects You can list all objects and their attributes in the Debug 
window. 


@ To list information about objects on the current 
screen: 


1. Choose Special Debug. 


The Debug window opens (see Figure 3-10). For complete 
information about the Debug window, see Chapter 11: 
Running and Testing an Application. 


2. Choose Objects List. 


LightShip lists all the objects on the current screen from 
back to front, with a number, type, screen position, and all 
other attributes associated with each object. 


- LightShip Debug vja 
File Edit Options... Objects List Variables List Palette List 


OBJ: Objects Listing 

bj: 8:1 Pes#.7135.57 Width:66 Height-:8i TIype-Decunent 
BJ: Scrolling - Horizontal:No Vertical:No Local:No 

Hidden:No User Edit:No Numeric Req. :No 

Text Color:O Background Color:47 

Font:Courier Size: 8 

Normal :-Yee Bold:No Italio:No Underline:No StrikeOut:No 
Source: Text 

User Entry: 

2 
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S=2 Pes.:213.52 Width:84 Height-:32 Type:Fornat 
Numeric:Yee Text Juetify:Right Bkgrnd. Colored:Yee 
Low Nunmber:2 Text Color:24 Bkgrnd.:-1 
High Number:4 Text Color:6 S8kgrnd.:-1 
Use Defaulte:No Negative: () Leading Zero:Yes 
Thoueande Separator:, Decimal Separator:. Decimal Places:2 
Prefix:$ Suffix: 
2-3 Pesx.-195.265 Width-84 Neight:29 Type-Braw Grp.8-1 
Shape:Reotangle Solid:Yee wWidth:4 Color:O 
8-4 Pes.-195.264 Width-85 UHeight-38 Type-Netspot CGrp.8-1i 
Text Required:No Highlight:No Gray If Inactive:No 
Highlight Type:None - Button Style 
Cursor file:Default 
Parametere: 
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Figure 3-10 Listing Objects 
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Creating an 
Object from the 
Tool Menu 


IS To align an 


object to the grid 
without turning the 
grid on, press 
CTRL before 
clicking the mouse. 


Creating an 
Object from the 
Toolbox 
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For more information about how order is important, see 
“Ordering Objects." 


@ To create an object from the Tool menu: 
1. Choose the object from the Tool menu. 


The cursor changes to a crossbar, indicating that you are 
in Create mode. 


-= i 
[We [dh Options View Specie! Too! Text Le 


+ 


Figure 3-2 Creating an Object 


2. Drag the mouse across the screen from left to right to 
create the object in the size you want. 


Or 


Click on the screen to create the object in the same size as 
the last selected object of that type. (Lines and polygons 
are an exception.) 


3. After you create the object, the cursor changes back to the 
pointer, indicating that you can select other objects. 


When you use the Toolbox, you select a tool and each time 
you click the mouse, you create another object of that type. 
Display the Toolbox when you are creating a lot of objects and 
you do not want to have to select the tool each time. 
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LightShip Levels 


Create Mode 


+- 


LightShip Levels and Modes 


LightShip has three levels: 

Author The Author level is for building applications. 

Browse The Browse level is for testing and running ap- 
plications. 

Capture The Capture level is just like the Browse level, 


except that it does not allow access to Windows 
or the Author level. The Control menu does 
not appear and the File Exit command and the 
Terminate Program action return to DOS. 


Unless you start LightShip using the /b (for Browse) or /c (for 
Capture) arguments, LightShip opens at the Author level. 


@ To move between the Author and Browse levels: 


Choose Special Author or press F4. 


Author Level Modes 


At the Author level, there are three modes: 


= Create 
= Select 
= Point 


Use Create mode to create objects. 
@ To enter Create mode: 


Choose a tool from the Tool menu or the Toolbox. The 
cursor becomes a crossbar. 


Drag or click the mouse to create the object. 
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4. When you are finished creating one type of object, select 
another tool or select the pointer at the top of the 
Toolbox to get out of Create mode. 


5. Double-click on the top of the Toolbox to put it away. 


Showing Hidden Objects 


Hotspot, menu, and format objects are normally hidden 
objects, that is, they are not displayed. You can also hide 
document objects if you choose. However, sometimes it is 
useful to display hidden objects. The commands described 
below display hidden objects at the Author level, but do not 
show them at the Browse level. 
@ To outline all objects with a dotted line: 

Choose View Outline All Objects. 
& To outline only hotspots: 

Choose View Outline Hotspots. 


@ To show format, menu, and hidden document 
objects: 


Choose View Show Hidden Objects. 


Selecting Objects 

You must select an object before you can do anything with it. 
When you select an object, a rectangle appears around it with 
resizing boxes in the corners. 


@ To select an object with the mouse: 


1. Ifthe cursor is not the pointer, choose Tool Select. 
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example, in Figure 3-12, the title "Point to Format Columns" 
tells you that are selecting data to format. 


The only objects that appear on the screen are document 
objects. All document objects display in Point mode, even 
hidden documents. 


LightShip: Point to Format Columns 


“+2 « 
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Selecting Data in Point Mode 


When you select data in Point mode, it is highlighted. The 
width of the area that highlights, called the selection range, is 
controlled by the Column Delimiter and Column Width 
settings on the Document menu. If you specify a column 
delimiter, the width of the selection range is the column 
widths you enter on the Column Widths dialog box. If you 
specify no column delimiter (None), LightShip interprets each 
row as One wide column and data highlights one character at a 
time. 


Selecting an 
Object in the 
Debug Window 


1. 
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To deselect an object with the keyboard: 


Press ESC. 


To select an object or group in the Debug window: 
Choose Special Debug. 
The Debug window opens. 


Choose Objects List. 


A list of the objects on the screen appears in the Debug 
window. 


LightShip Debug 
File Edk Options... Objects List Variables List 
Palette List 


OB Parameters: 
OBJ : Aotione: 
OBJ : 1: Function cloeseeflag := O ba 
OBJ : 2: Open File - Add to Retrace Path, | RiiREEEE==>=n@peetneeenennnneenas 
bj z 8:27 Pes .-362,82 Vidth-286 Hei. SNL LALLA 
OBJ : Text Required:No Highlight:No Grape e eee cere eee ties oe) 
OB : Highlight Type:None V ONIRA EA TEN: 
OBJ : Cursor file:Default a a oO 
OBJ : Parameters: EEN ek oy YS es 
OBJ : Actione: cee BP ox tae BH SS 
OBJ : 1: Function closeflag := O S TA Aa 
OBI : 2: Open File - Add t>o Retrace Path, f: ns 

bj- 8:28 Pee.-436.15 Width-154 Nej- PE RSE 
OBJ : Name:&&callerror Item: Separator: #4 oe RR 
OBJ : Parametere: Be fh On RRR RRR 
OBJ : 1: Function closeflag := O il orearen SO ANI 5 cig 
OB : 2: Open File - Add to Retrace Path, | Beesesssessssssesscessccesceseeees 
bj: 8:29 Pes.:223,3 Width-172 Weij- 
OBS : Source:Clipboard . 
OBJ : Save Palette:No Fit Obj. To Image:}: kee mre mene 
OBJ : Scaling - Horizontal:1.00 Vertical | PRAA SESS SSS SSS SSS SSOS SS § 
bj: 8:38 Pes.:362.269 Width:2868 Né- Bs : 

BJ : Text Required:No Highlight:No Graj: Eo 


Highlight Type:None —— ERS 
Cursor file:Default ~ 
Parameters: RSs 
Aotione: 

1: Function closeflag := O 
2: Open File - Add to Retrace Path,} 

8-31 Pee.-2809,.188@ Width-:158 Nç 

Name: AAclose Item: Separator:No Bm SNNN 
Parametere: 


OREA E; 
O Poy 
Figure 3-5 Selecting an Object in the Debug Window 


OO good Oo g 
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Cteecce 
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Double-click on the bold line in the Debug window that 
identifies the object. 


This selects the object or group on the LightShip screen. 
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You use the tools on the Tool menu to create objects. The fol- 
lowing tools are available: 


Draws a graph of numeric data. 


Displays text, usually from an external data 
source such as a DDE Request. 


Draws rectangles, circles, lines, and polygons. 


Formats data and colors variances in document 
objects. 


Creates an area of the screen that performs an ac- 
tion when you click on it. 


Displays images from the Clipboard, PCX files, 
BMP files, or DDE Requests for bitmap data. 


Creates menu-bar menus and menu items that 
perform actions. Also creates special menu 
objects that perform actions but are not 
displayed. 


Displays text, for example, headers, titles, labels, 
button names. 


Selecting 
Overlapping 
Objects 
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© To select additional object(s): 


Hold down the SHIFT key and click the object you want to 
select or click and drag to select multiple objects. 


© To deselect only one of the selected objects: 


Hold down the sHIFT key and click the object you want to 
deselect. 


© To deselect all the objects: 


Click anywhere else on the screen background or press 
ESC. 


Multiple objects and groups might overlap or completely cover 
each other. To select overlapping objects, use the CTRL key 
with the UP ARROW Or DOWN ARROW keys. This only selects 
objects that intersect the point on which you clicked the 
mouse. 


© To select the next object back: 

Press CTRL+UP ARROW. 
E To select the next object forward: 

Press CTRL+DOWN ARROW. 
If you don’t select the object that you want, try clicking in 
another spot. You can usually tell which object is selected by 
looking at the menu to the right of the Tool menu. If two 
objects of the same type are overlapping, you need some other 


way of telling which is selected, for example, by looking at the 
action or the source of the object. 
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Creating Objects 
in Back 


Creating an Object 


You create an object by choosing it from the Tool menu or the 
Toolbox and then clicking or dragging the mouse on the 
screen. When you use the Tool menu, you must select a tool 
each time you create a new object. When you use the 
Toolbox, you create a new object every time you click the 
mouse. The Toolbox stays displayed on the screen until you 
put it away. Use it when you are creating a lot of objects and 
you do not want to select the tool from the menu each time. 


When you create or select an object, a menu for that object 
type appears to the right of the Tool menu. The settings on 
this menu determine the attributes that the object has when it 
is created. Use this menu to define the object in more detail. 
For example, in Figure 3-2, the Text menu allows you to enter 
text, and choose colors and fonts for the text. 


Some objects might be hidden so that they do not display 
unless they are selected. If you cannot see an object when it is 
not selected, choose View Outline All Objects or View Show 
Hidden Objects. For more information, see the next section 
"Showing Hidden Objects." 


You can have up to 1,000 objects on each screen. 


Objects are created in front of each other by default. In other 
words, the first object you create is the furthest back and has 
the lowest number in the Debug window object list. You can 
reverse this so that new objects are created behind existing 
objects rather than of in front of them. This can be useful 
when the order of objects is important, such as hotspots and 
menu objects. 


@ Tocreate new objects behind existing objects: 


Choose Special Create in Back. 


For One Object 
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N 


Change the settings on the object’s menu. 


ii 


Create the object by dragging or clicking the mouse. 


@ To set attributes for a specific object only: 
1. Choose the object from the Tool menu. 
2. Create the object by dragging or clicking the mouse. 


3. Choose the object’s menu and assign attributes. 


Ordering Objects 


LightShip treats objects as if they have a front-to-back order. 
The order and position of objects affects the appearance and 
the behavior of an application. For example, if two or more 
hotspots or menu objects are overlapping, the action(s) of the 
one in front are executed first, then the actions of the next one 
back, and so forth. 


The front-to-back order of menu objects also affects the order 
in which menu names and items appear. The menu name that 
is furthest back appears first on the menu bar. The menu in 
front of that one appears next on the menu bar and so forth. 
Menu items behave the same way; the menu item furthest back 
appears first on the menu and the menu item in front of that 
one appears second. 


Objects are initially ordered in the order in which you create 
them. The first object you create is considered "furthest back" 
and each subsequent object you create is "in front" of the one 
before. You can change this so that each new object you 
create is furthest back by choosing Special Create In Back. To 
move an object forward or back, use the Special Send com- 
mands. For more information, see "Moving and Resizing 
Objects." 
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@ Tocreate an object from the Toolbox: 


1. 


Choose Tool Toolbox. 

The Toolbox appears on the screen. 

Select the tool you want. 

If you select the Draw tool, the draw tool icons appear on 


the right side of the Toolbox. Figure 3-3 shows the 
Toolbox with the draw tool icons displayed. 


LightShip - Untitled 
File Edit Options View Special Tool Draw 


Figure 3-3 Using the Toolbox 


Drag the mouse across the screen from left to right to 
create the object in the size you want. 


Or 


Click on the screen to create the object in the same size as 
the last selected object of that type. 
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ia To prevent 

the screen Moving and Resizing Objects 

repainting when 

moving and You can move the selected object(s) or group(s) by dragging 
resizing, turn off them with the mouse. The cursor changes to a four-headed 
View Preferences arrow. 


Redraw During 


LightShip Untiticd 
File Edit Qptions Yiew Special [ool Draw 


Move/Resize. 


Figure 3-7 Moving an Object 


Moving an Object @ To move the selected object or group forward or 
or Group Forward backward: 
or Backward 
1. Select the object or group by pressing CTRL+UP ARROW or 
CTRL+DOWN ARROW. 


2. Choose one of the following options on the Special menu: 


= Choose Send Backward or press F7 to move the se- 
lected item backward by one object. 


= Choose Bring Forward or press SHIFT + F7 to move the 
selected item forward by one object. 


LightShip User’s Guide 


The cursor changes to the pointer, indicating that you are 
in Select mode. 


2. Click on the object. 
If there are overlapping objects, the front-most object is 


selected. A border displays around it as shown in Figure 


3-4. 


LightShip Untiticd 
File Edit Qptions Yiew Special [ool Draw 


Figure 3-4 Selecting an Object 
@ To deselect an object with the mouse: 
Click elsewhere on the screen background. 
@ To select an object with the keyboard: 
Press CTRL+RIGHT to select objects from back to front. 


Press CTRL+LEFT to select objects from front to back. 
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Aligning Objects 


You can turn on Grid Snap, display grid lines, or use the CTRL 
key to help you align objects on the screen. The grid only 
appears at the Author level. 


There are two ways to use Grid Snap. If no object is selected 
when you turn Grid Snap on, objects snap to align with the 
nearest grid line as they are created. If you select an object be- 
fore turning Grid Snap on, you can make other objects snap to 
align with that object. 


Turning On the @ To turn on the grid: 
Grid 
1. Choose View Grid. 


ISF Hold down 
the CTRL key when 
creating, moving, or 


A dialog box appears. 


Grid 
resizing objects to 
snap to the grid C] Grid Snap 
when Grid Snap is 


not on. 


C Show Grid 


Vertical Increments: inches 
Horizontal Increments: inches 


Figure 3-9 Setting Grid Increments 


2. Enter the grid increments by typing a number in the 
Vertical and Horizontal Increments boxes. 


The vertical and horizontal increments control the 

amount of space between the grid lines. The number 

must be between 0.10 and 1.00. It is saved in LS.INI. 
3. Select the Grid Snap box to turn grid snap on. 


4. Select the Show Grid box to show the grid. 
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Chapter 4 


Displaying Data 


This chapter describes how to display, format, and color 
variances in data. 


What is a Document Object? 


You display data by creating a document object and then 
specifying the source of the data. Figure 4-1 shows a 
document object that displays news stories using a DDE 
Request to a database. 


Newstrack National News 


News Ira | 


CHEAPER BORROWING MAY FAIL TO WOO UK VOTERS IN GENERAL ELECTION 
ANALYSTS SAY UNDERLYING UK INFLATION RATE MAY STILL POSE PROBLEMS 
EX-FED GOV. JOHNSON SAYS CPI FALL GIVES FED FLEXIBILITY 

WORLD BANK APPROVES $150 MILLION FOR CHINESE PROVINCE 

CONGRESS SET TO STEP IN IF FREIGHT RAIL SERVICE DISRUPTED NEXT WK 
MEXICAN PRESIDENT SUPPORTS INCREASING TRADE WITH U.S. 
INDIA TO VOTE IN MAY TO ELECT NEW FEDERAL, STATE GOVERNMENTS 


Figure 4-1 A Document Object 
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Displaying @ To display negative numbers with parentheses: 
Negative 
Numbers Turn on (237.50). 


@ To display negative numbers with a minus sign: 


Turn on -237.50. 


Displaying and @ To suppress leading and trailing zeros: 
Hiding Zeros 
Turn on .7. 


If you turn zero display off, leading and trailing zeros do 
not display. 


To display leading and trailing zeros: 
Turn on 0.70. 
If you turn zero display on, all trailing zeros display, but a 


leading zero appears only if there are no digits to the left 
of the decimal place. Only one leading zero will display. 


Displaying To enter a symbol to use as a separator: 

Separators in 

Numbers Type a symbol in the 1000 Separator text box. For 
example, type a comma to display 1000 as 1,000. Leave 
the text box blank to display no separator. 

Displaying @ To enter a symbol for a decimal separator: 

Decimal 

Separators Type a symbol in the Decimal Separator text box. For 


example, type a period (.) to use a dot as a decimal 
separator. Make the text box blank to have no separator. 
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Specifying If you select any option except None, you can specify up to 20 
Column Widths columns for a document object. 


@ To specify column widths: 
1. Choose Document Column Width. 


A dialog box appears. 


Document Column Width 


Figure 4-12 Specifying Column Widths 
2. Type one or more numbers for each column. 


These number(s) represent the characters across the col- 
umn. If you enter a number for each column, the column 
widths are set to the numbers you enter. If you enter one 
number, it is interpreted as the width for every column. If 
you enter less numbers than there are columns, the last 
number repeats for the extra columns. For example, if 
you have six columns and you enter "10 15" the column 
widths will be "10 15 15 15 15 15." 


You can enter a zero to hide a column that you do not 
want to display. Columns to the right of a hidden column 
move to the left. 


3. Choose OK. 
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Justifying Numbers or Text 


$ 


To justify columns of numbers or text: 
Select the format object. 


Choose Format Text Only if all you want to do is align 
columns. Numeric formatting turns off. 


Choose Format Justification None, Left, Center, or Right. 


None is only available if Format Text Only is on. 


Displaying Format Objects 


Format objects do not normally show on the screen. You only 
see a rectangle when they are selected. 


To display format objects: 

Choose View Show Hidden Objects. 

All format objects appear with the word Format on them. 
Menu objects also display when View Show Hidden 
Objects is on. 

Or 


Choose View Outline All Objects. 


All objects on the screen are outlined with a dotted line. 
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iS Hint Document objects scroll fastest when they do not intersect 
with any other objects. 


Scrolling a @ To scroll up or down one line at a time: 
Document Object 
Click the vertical scroll arrows, or press the UP ARROW or 
DOWN ARROW keys. 
@ To scroll up or down one page (screen) at a time: 


Click on either side of the vertical scroll box, or press the 
PGUP or PGDN keys. 


@ To scroll sideways a line or column at a time: 


Click the horizontal scroll arrows, or press the RIGHT ARROW 
Or LEFT ARROW keys. 


@ To scroll sideways a page at a time: 


Click on either side of the horizontal scroll box. 


Adding Window Scroll Bars 


You can add vertical and horizontal scrolling capability to a 
document at the Browse level. Scroll bars only appear when 
the document is too large to display in the document object. 
You have the option to add scroll bars to the application 
window, which will scroll all scrollable documents, or to add 
local scroll bars to individual document objects. 


You can choose Options Hide Scroll Bars to hide scroll bars on 
the application window at the Browse level. 


@ To add scrolling to a document object at the Browse 
level: 


1. Select the document. 
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Disabling Formats 
View Disable Formats only disables formats at the Author level. 


@ To disable formats without changing any format 
settings: 


Turn on View Disable Formats. 


To enable formats again: 


Turn off View Disable Formats. 


Coloring Variances 


Variances are numbers that are greater or less than budgeted 
or projected figures. LightShip allows you to color variances 
differently than numbers that fall within an expected range. 
This is a useful feature for exception reporting. 


You use format objects to define conditions to flag and color 
variances. LightShip colors the numbers associated with the 
format object if they meet the conditions. For example, Figure 
4-21 shows a document where any negative number appears 
with a colored background. 


A data that is formatted and colored by a format object is 
called the destination; the data used for comparison is called 
the source. Usually, the destination and the source are the 
same, however, you can define separate data as the source. 
For more information, see "Using a Separate Source to Define 
Variances" later in this section. 


It is also possible to color a format object based on conditions 
you define. For more information, see "Coloring a Format 
Object" later in this section. 
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May 1991 


Actual Budget Yariance 
To Budget 


Headcount 

GROSS SALES 

Less: Returns /Allqence 
NET SALES 


DIRECT COST OF SALES 
Percentage 


GROSS PROFIT 
Percentage 


Figure 4-13 A Document Object with Local Scroll Bars 


Scrolling by Page 


Documents scroll line by line by default when you use the 
scroll arrows or the DIRECTION keys. You can change it so thata 
document only scrolls a page at a time (even with the scroll 
arrows or the UP ARROW and DOWN ARROW keys) at the Browse 
level. A page is defined by the number of lines displayed in the 
document object. 


When Scroll By Page is off, document objects with the same 
number of lines scroll together line by line. If one of them has 
less lines than another, it stops scrolling first. When Scroll By 
Page is on, document objects with the same number of lines 
scroll simultaneously. Document objects with a different 
number of line items scroll in relation to each other, de- 
pending on the number of lines in each document. For exam- 
ple, if one document object has half as many lines as another, 
it scrolls one line to the other document’s two lines. 
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A dialog box appears. 


Format Colors 


C] Color Format Object 
Low Value High Value 


Figure 4-22 Defining Variance Conditions 


4. Type a number in the Low Value or High Value text box, 
or both. 


You can also type a variable reference. 
Selecting a Color The default color for the low value is grey, while the default 

color for the high value is blue. 

@ To select a color other than the default: 

1. Choose the Color button. 
The dialog box shown in Figure 4- 23 appears. 

2. Select the color for the number(s). 

3. Select the color for the numbers’ background, or choose 
the Transparent button to make the background transpar- 


ent. 


4. Choose OK. 
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ISF The quickest 
way to color is to 
press F5 and then 
double-click on the 
color. 
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@ To reset the Bottom-right Corner: 


Turn it off and on again. 


Coloring a Document Object 

@ To color the data and background in a document: 
1. Select the document object. 

2. Choose Document Color or press F5. 


A dialog box appears. 


Text Color 


Sie 


Figure 4-14 Assigning Colors 
3. Select the color for the text. 
4. Select the color for the background or click the 
Transparent button to make the background of the docu- 
ment transparent. The color behind the object will show 


through. 


5. Choose OK. 
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Using the Format Colors dialog box, we typed a "1" in the Low 
Value text box. Then we choose the Color button and selected 
a foreground and a background color. 


Format Colors 


C Color Format Object 
Low Value High Value 


<= Normal >= 


Figure 4-25 Defining the Variance Condition 


Using a Separate Source to Define Variances 


You can use a separate data source for determining variances 
than the data being colored. The data that is formatted and 
colored by the format object is called the destination; the data 
that contains the numbers that are used for comparison is 
called the source. This is useful when the exception involves a 
calculation or a flag in database records, for example. 


LightShip compares the source against the low and high values 
when you use the Source option on the Format Colors dialog 
box. The items in the source have a one-to-one relationship 
with the items in the destination. If you have less items in the 
source than in the destination, the extra items in the 
destination do not display variances. If you have more items 
in the source than in the destination, the extra items in the 
source will be ignored. 


[= Note The destination document and the source document are the 
same by default. If there is no separate source document, the 
destination document serves as the source. 
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Text Font 


Swiss Monospaced 
Terminal 


[C] Italic 
Li Underline 
[_] Strikeout 


C] Printer Fonts 


Size: 
x Fixed Pitch [z5 | 


Text some 


Figure 4-15 Choosing a Font 


@ To list proportional screen fonts and font sizes: 


Make sure the Printer Fonts and Fixed Pitch check 


boxes are turned off. 


Use proportional fonts for document objects with No 


Columns, Word Wrap, or Fill on. 


@ To list available printer fonts and font sizes for 


the current printer: 
Turn on the Printer Fonts check box. 


Select the font you want. 


A sample of the selected font appears in the Text Sample 


box. 


Select the point size from the Sizes list box or type it in 


the Size text box. 


Unless you have a Type Manager, if you type in a size that 
is not available, LightShip uses the closest available size. 


We recommend selecting a point size from the list. 
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Figure 4-27 Selecting Source Numbers 


The Actual numbers are colored according to the conditions 
defined on the Format Colors dialog box and by the numbers 
defined as the source. 


File 


Edit Options 


DALUTOHIALY XCI PILISI 
Tool 


Lightship 


View Special 


Paper Income Statement 


July, 1991 Actual Budget 


GROSS SALES 

Less: Returns/Al lowance 
NET SALES 

DIRECT COST OF SALES 
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NET PROFIT $13,806 


(Peer ] 


Figure 4-28 Coloring Variances Defined by a Separate Document 


aad 
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When you select a document object, formatting is disabled and 
the document appears as it did before it was formatted. As 
soon as you deselect it, it displays the formatted data. 


You can optionally color format objects based on conditions 
you define. Use this feature to hide or display another object. 
For more information, see "Coloring a Format Object." 


Format objects do not normally display on the screen unless 
View Show Hidden Objects is on. 


Format Object The following rules apply to format objects: 
Rules 
= One format object can only apply one format, that is, one 
set of attributes. 


= You can use one format object to format multiple columns 
of data in multiple documents. However, each item that 
you format can only be formatted by one format object; 
that is, it can only be highlighted once in Point mode. The 
document object(s) formatted by a format object are 
called the destination object(s). 


= The width of the area that highlights in Point mode is de- 


pendent on Document Column Delimiter and Document 
Column Width settings. 


Creating a Format Object 

The size of a format object is not important, but it is a good 
idea to put it where you can see it when View Show Hidden 
Objects is on. 

© To create a format object: 


1. (Optional) Choose View Hidden Objects. 


2. Choose Tool Format. 
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Coloring a Format 
Object 


Example 
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| If the number in the red box is greater than the 
| number in the yellow box, Stars & Stripes will appear! 


Figure 4-29 Creating an Image Object 


@ To color a format object: 

1. Create or select a format object. 

2. Define the destination or source data, or both. 
3. Define the conditions. 


4. Define the colors so that the text color of the low or high 
value is the color of the screen background. 


5. Choose Format Color. 
6. Choose OK. 
Let’s look at the example shown in Figure 4-29. After creating 


the image object, you would create a format object large 
enough to cover the image object. 
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Figure 4-17 Point Mode 


Selecting Data to @ To select the data: 


Format 
1. Drag the mouse over the items that you want to format. 


l igħtShip: Paint ta Format Calumns 
Cancel! 


Actual 


“General e AdMINISTrat longer 
wos Selling é Marketing CR: 
“8 Research a Development 
Miscellaneous 


Figure 4-18 Selecting Columns 
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The Document 
Menu 


Formatting a 
Document Object 


A document object can display data: 


= From an ASCII text file 

From an application that uses Window’s DDE protocol 

= That you type in from the keyboard, either at the Author 
or Browse level 

= From a variety of other external sources, such as dBASE® 
files and SQL servers 


When you create or select a document object, the Document 
menu appears on the menu bar. Use this menu to: 


Change the data source. 

Specify layout, column delimiters, and widths. 

Hide the document. 

Add scroll bars. 

Anchor the data to the top and bottom of the window. 
Enable data entry in a document object at the Browse 
level. 

Choose colors for the data and background. 

Choose a font, point size, and style for characters. 


You format the data in a document by creating a format object. 
Format objects allow you to: 


= Align text or numbers 
= Format numbers, for example, $1,000.00 
= $Color variances in the data 


When Document Object Data is Updated 


LightShip displays the most current data in a document object 
whenever you open a screen. LightShip also automatically 
updates document objects at other times, as described below. 
In addition to automatic updates, you can manually update 
document objects by issuing a Calculate Now command. 
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Numeric Format 


C Use Defaults 1000 Separator |. | 


Negatives Decimal Separator |. | 

© (237.50) 
oat Decimal Digits [0 | 
Preti [s] 


Suffix | | 
Doo 


Figure 4-20 Formatting Numbers 


Initially, the settings in this dialog box are taken from the 
Country settings in the [intl] section of your WIN.INI file. 
To change these settings, open the Control Panel and 
choose Settings International. 


@ To use the settings in WIN.INI to define the 
numeric format: 


Turn on the Use Defaults option. 


When this option is on, any change you make to the 
Country settings is also made in LightShip. The 
WIN.INI settings override any other settings in this 
dialog box except the Multiplier. If you prefer to 
leave Use Defaults off, you can still make the settings 
match those in WIN.INI by choosing the Default but- 
ton. 


4. Otherwise, make your selections. 


5. Choose OK. 
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ligqhtShinp - Untitled 
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; DDE Data Request... 
“| User Entry... 


Figure 4-2 Specifying a Data Source 
4. Choose one of the menu items. 

= Choose Text File to display an ASCII text file. For 
more information, see the next section "Displaying a 
Text File." 

= Choose DDE Data Request to display data from an 
application that uses DDE. For more information, see 
"Displaying Data from a DDE Request." 

= Choose User Entry to type data into the document 


object from the keyboard. For more information, see 
"Creating a User-Entry Document Object." 


Displaying a Text File 
Text files must be in ASCII text format. 


When you choose Text File from the Document Source menu, 
the Document Text File dialog box appears (see Figure 4-3). 


4-4 


Displaying 
Decimal Digits 


Displaying a 
Prefix 


Displaying a 
Suffix 


Choosing a 
Multiplier 
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@ To specify the number of decimal digits to display: 


Type the number of decimal places you want after the 
decimal separator. Enter a zero for none. Make this text 
box blank if you want a General format. A General format 
has floating decimal places as required by the data, and 
decimal points are not aligned (see below). 


S12.123 
$-11.65 
$0 

$1 

$0.374 
$0.01 
$136 .5987 


@ To display a numeric prefix: 
Type a symbol, for example, dollars ($) or yen (¥), in the 
Prefix text box. 

@ To display a numeric suffix: 

Type a suffix, for example, DM, in the Suffix text box. 
Choose a multiplier if your numbers are too large to display 
on the screen. 

@ To specify a multiplier: 


Type a decimal number that you want to multiple by. For 
example, to display 1,000,000 as 1,000, type .001. 
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4. Position the data in the document object with the scroll 
bars, or the DIRECTION or PAGE keys. 


For information about defining scrolling attributes, see 
"Scrolling a Document." 


5. Resize the document window so that only the data you 
want is showing. 


Displaying Data from a DDE Request 


When you choose DDE Data Request from the Document 
Source menu, the dialog box shown in Figure 4-4 appears. 
This figure shows a DDE Request to an Excel spreadsheet. 


Documert DDE Data Request [ox } 
Application: ETE 


Topic: | e:\excel\annual xis 
i E 


Paste Link ` 


XX] Auto Start Program 


Command Line: 


Startup Directory: 


Figure 4-4 Defining a DDE Data Request 


The program that you are requesting data from is called the 
server or the server application. It must support the Clip- 
board Text (CF_TEXT) format. This is a basic format sup- 
ported by most applications. 


The exact form of the DDE Request varies, depending on the 
server application. However, all applications using DDE must 
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Changing a Format 

& To change destination data: 

1. Select the format object. 

2. Choose Format Destination. 
The Point mode screen appears. 


3. Choose Clear All! to deselect all highlighted areas or 
choose Undo! to deselect the last area you selected. 


4. Select the items you want. 


5. Choose OK! on the menu bar. 


Changing © To change numeric formatting: 
Numeric 
Formatting 1. Select the format object. 


2. Choose Format Numeric Format, press F2, or double-click 
on the format object. 


3. Make your selections. 

4. Choose OK. 
Changing © To change justification: 
Justification 


1. Select the format object. 


2. Choose Format Justification None, Left, Center, or Right. 
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Figure 4-5 Pasting Data from the Server 
4. (Optional) To start the server application in a different di- 
rectory than the current one, type the drive and directory 
in the Startup Directory text box. 


This lets you use files in that directory without specifying 
a path. The current working directory remains the same. 


5. Choose OK. 
The data appears in the document object. For informa- 


tion about changing column widths, see "Defining 
Columns." 
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DDE Requests 


Text Files 
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When Calculation Automatic is on, document objects whose 
source is a DDE Request are updated when: 


= Source data changes. 
æa A literal or variable reference in a DDE Request dialog box 
changes. 


When Calculation Manual is on, if you make a literal change to 
a DDE Request dialog box, you are prompted to execute the 
request. 


Document objects whose source is a text file are always up- 
dated when you make a literal change to the filename. If 
Calculation Automatic is on, and a variable reference in the 
filename changes, the document object is also updated. 


Creating a Document Object 
© To create a document object: 


1. Choose Tool Document. 


~ 


Drag or click the mouse to create the object. 


- 


Choose Document Source, press F2, or double-click on the 
document object. 


The Document Source menu displays, as shown in Figure 
4-2. 
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Figure 4-6 Typing in Data 


2. To finish, press ENTER. 


Creating a You might want to create a customized list of chart labels or 
Customized List values to assign to variables in Point mode. For example, 
Figure 4-7 shows a list of chart labels. 


LiyhtShip - E:\EXAMPLES\CHAP4\CUSTL STL SF 
File Edit Qptions View Special [ool Document 
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OBSESSED SLE SOME 


Wises psn ay 
Ns neat etereee “ 
fave 'e e's SESS S22, << SSP 
OSX SS KS Ş SS . a — — am KS 
8 ` | Wè SS BRE . Se $S : eS ms aK _ ae SS SK SS ree 
A SPR SS Bx SS 
SSSA OR OR BOO _ 
> a SS Ste RS ~ < RS ~ & ESS CC RY 
ESS DNE ONON AO SS SES > SEES SSE SS 
scarce 
‘Cosi of Sales : 
‘Commissions ;: 
: Other : 
Siccaneraneacunrennnccencmnnnnns š 


Figure 4-7 Typing in a List 
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Lightship - E\DATA\OIL.LSF 
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Ol Price Ber Galion 
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1991 


Figure 4-21 Displaying Variances 


Defining Variances 


The Format Colors dialog box allows you to define the low 
and high variance values and select the colors associated with 
them. Ifa number is less than or equal to the low value, or 
greater than or equal to the high value, it is colored accord- 
ingly. If not, the numbers remain the same color as the rest of 
the document object. The numbers are colored based on 
actual numbers displayed in the document object without 
taking the Multiplier (from the Numeric Format dialog box) 
into account. 


@ To define conditions for coloring variances: 
1. Create or select a format object. 


2. Choose Format Destination and select the data you want 
to format. 


3. Choose Format Color or press F5. 
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Figure 4-9 Displaying Chart Labels from a User-Entry Document 


Creating an Interactive document objects allow you to type into them at 
Interactive the Browse level and cause some other action to be executed. 
Document You can also have hotspots behind the document, which 


execute after data entry happens. 


To create an interactive user-entry document, you must turn 
on Document User Edit and type a variable reference into the 
document object. Any text that you type into the document at 
the Browse level is stored in the variable and appears in the 
document. A variable value also appears in the document at 
the Author level. The variable reference does not show on the 
screen, unless you choose Document Source and then User 
Entry. 


[= Important If you enter text, a nested variable reference (for example, 
@(@(item))), or multiple variable references, and type into 
the document at the Browse level, whatever was in the 
document object previously is overwritten. No values are 
stored in nested or multiple variances references. 


4-12 


Example 


Chapter 4 Displaying Data 


Low Value Foreground Color 


| ransparent — 


Figure 4-23 Defining Variance Colors 


@ To switch the colors of the low and high values: 


Choose the Swap button. 


This example shows how we defined the variances shown in 
Figure 4-21. First we created a format object and then selected 
the range of numbers shown in Figure 4-24. 


Lightship - Point te Format Columos 
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Figure 4-32 Coloring the Format Object Hides the Image 


If the source number is less than the high value, the format 
object is not colored and the object beneath it is displayed. 


ee ene ete Stars $ Stipes wil appear 
Enter a number in the ted box... 


Figure 4-33 Displaying « a ı Conditional Image 


4-48 


Chapter 4 Displaying Data 


Example In this example, we use a list of variance numbers in a hidden 
document object as the basis for coloring figures in another 
document object. The destination document object displays 
Actual and Budget figures. We want to color any Actual 
number whose corresponding variance number is a negative 
number. 


We defined a format object and selected the Actual numbers as 
the destination. 


Lightship - Point to | ormat Columns 
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Figure 4-26 Selecting Destination Numbers 
Then we chose Format Color, entered a ".50" in the Low Value 


text box, and chose the Source button. Then we selected the 
variance numbers as the source. 
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4. Define @(file).txt as the source text file for the other 
document. 


- Lightship vja; 


Consolidated Income Statenent 


July. 1991 Actual Budget Variance 
To Budget 


Headcount 2,971 2.989 (18) 


SALES 331.873 315.033 ; 
Less: Returns“Allowance 15.046 13.354 1.692 
NET SALES 316.827 301.679 15.147 
DIRECT COST OF SALES 150.486 108.567 44.918 
GROSS PROFIT 166.341 196.112 (29.774) 


Text File Document 
Object 


28.688 28.414 274 
Sales & Marketing 60,741 59,415 1,325 
Research & Developarent 26,001 27.625 (1,623) 
Miscellaneous 11,334 10,700 634 
TOTAL OPERATING EXPENSE 126,764 126,154 610 


File Name 


User-Entry, User-Edit 
Document Object 


Figure 4-10 An Interactive Document 


5. At the Browse level, click in the user-edit document and 
type a filename. 


The file appears in the document object that has 
@(file).txt defined as its source. 


Editing a User- @ To edit text in a user-entry document: 
Entry Document 
1. Select the document object. 


2 Choose Document Source, press F2, or double-click on the 
document object. 


4. Choose User Entry. 


The document appears with the data in it highlighted. 
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@ To select data in a separate source document object: 
1. Select the format object. 

2. Choose Format Color or press F5. 

3. Enter the conditions and colors. 

4. Choose the Source button. 


The screen changes to Point mode. By default, the desti- 
nation document and the source document are the same. 


5. Choose Clear All! on the menu bar to deselect the data 
formatted by the destination document. 


6. Select the items that you want in the source document. 
7. Choose OK! on the menu bar. 


8. Choose OK on the Color Format dialog box. 


Coloring a Format Object 


By default, format objects do not display at the Browse level. 
However, you can color a format object if the condition 
defined in the Format Colors dialog box is true. When the 
destination (or source) data is less than or equal to the low 
value, or greater than or equal to the high value, the format 
object is colored. 


You might use this option when you want to hide or display a 
message or button that is underneath the format object. For 
example, you could display an image object on the screen as 
shown in Figure 4-29. 
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Defining the Layout 


You can define a document object so that it is has columns or 
the text wraps to fill the document. The default layout for 
document objects is columns. You can change this on the 
Document Layout menu. The following options are designed 
for the display of text rather than columns: 


= No Columns 
= Word Wrap 
= Fill 


Proportional fonts use proportional spacing on document 
objects with Document Layout No Columns on. Document 
objects laid out with columns can use proportional fonts but 
do not use proportional spacing. 


Format objects do not affect document objects affected by No 
Columns, Word Wrap, and Fill. 

@ To define the layout: 

1. Select the document object. 

2. Choose Document Layout. 

3. Choose No Columns, Word Wrap, or Fill. 


= Choose No Columns for the data to appear the same 
as in the source document. 


= Choose Word Wrap for data to wrap to the next line 
depending on the size of the document object and on 
line feeds and carriage returns in the source 
document. A line feed followed by a carriage return 
in the source document ends a line. Two carriage 
returns create a new paragraph. 
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lf the number in the red box is greater than the 
number in the yellow box, Stars & Stripes will appear! 


Enter a number in the red box... 


Figure 4-30 Creating a Format Object 


Then you would choose Format Colors, define the conditions, 
and turn on Color Format Object. You would choose the 
color to match the color of the screen background. In Figure 
4-30, the document object displaying "100" is the source of the 
format object. We entered the high value as "100." 


Low Value High Value 


Figure 4-31 Specifying Format Colors 


LightShip checks the first number in the source document. If 
the number is greater than or equal to the high value, the 
format object becomes the text color defined for the high 
value. This hides the image. 
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To specify a column delimiter: 


Choose Document Column Delimiter. 


Choose the delimiter that marks the division between 
columns. 


Choose None when you do not want to define 
columns. This is the default when the source is a text 
file. 


Choose Tab if tab characters are used as column 
delimiters in the document. LightShip creates a new 
column for each tab character in the document. This 
is the default when the source is a DDE Request or 
user entry. 


Choose Comma if commas are used as column delim- 
iters in the document. LightShip creates a new 
column for each comma in the document. 


Choose One Space if there are one or more 
consecutive spaces between columns in the 
document, but not within a column. LightShip creates 
a new column for each space in the document. 


Choose Two Spaces if there are two or more 
consecutive spaces between columns in the 
document, but not within a column. LightShip creates 
a new column whenever it encounters two or more 
spaces in the document. 


Choose Use Column Width to set each column to the 
number of characters you specify in the Document 
Column Width text box. This option is useful when 
data has a fixed column width and no delimiter 
character. This option only changes the way a doc- 
ument appears on the screen when you format it with 
a format object. 
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Displaying Special Values 


Many applications use a particular string, such as NA, to de- 
note a "not available" value in a data field. If you expect such 
values in your source data, you can specify the input strings 
you expect and how to display them on the screen. You do 
this by defining two settings in the Preferences dialog box: 


= NA stores incoming values. 
= OUTNA stores one output value. 


Document objects must be formatted to display the OUTNA 
value that you specify. 


NA settings are global. They are saved in LS.INI if you save the 
settings in the Preferences dialog box. 


Incoming Values You can define as many incoming values as you want; 
however, an NA input string cannot begin with a digit, a minus 
sign, an Open parenthesis, a closed parenthesis, or a period. 
LightShip does this to prevent an actual number from being 
interpreted as not being available. 


Specifying @ To specify how special values will appear: 
Special Values 
1. Choose View Preferences. 


The dialog box shown in Figure 4- 34 appears. 


“i 


Click in the NA - Incoming Values text box and type the 
incoming values you expect, separated by a semicolon. 
For example: 


KeEKONA 
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Hiding a Document Object 

You can prevent a document object from displaying with the 
Document Hidden command. Use hidden documents to point 
to intermediate data that you do not want to display; for 
example, chart data, variable values, or function arguments. 

@ To hide a document: 

1. Select the document. 


2. Choose Document Hidden. 


@ To display a hidden document without changing its 
hidden attribute: 


Choose View Show Hidden Objects. 

or 

Choose View Outline All Objects. 
® To turn off a document object’s hidden attribute: 
1. Select the document. 


2. Turn off Document Hidden. 


Scrolling a Document Object 


When you select a document object at the Author level, scroll 
bars appear on the LightShip window if the data in a docu- 
ment object extends beyond the document object window. 
You can use the scroll bars, the DIRECTION keys, or PAGE keys to 
scroll. 
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Enter the filename. 


Select a filename from the list of files, type the filename, 
or type an asterisk (*) to list a subset of files in the Files 
list box. For example, to list only files that end in ".TXT," 


type: 
*. txt and press ENTER. 


Document Text File 
foe PS 


Directory: e:\data 


Directories: 
boston.txt 


strings.txt 


DX] Search Path 


Figure 4-3 Selecting a Text File to Display 


Turn on Search Path if you want LightShip to search 
through the current working directory first and then ina 
search path that you define. (For more information about 
how to define a search path, see Chapter 2: Applications, 
Screens, and Files.) Otherwise, if you want LightShip to 
search for the file only in the directory specified on the 
dialog box, turn Search Path off. 


Choose OK. 


The file appears in the document object. The columns 
may not be aligned or spaced correctly. For information 
about formatting a document, see "Defining the Layout" 
and "Formatting a Document Object." 
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2. Choose Document Vertical Scroll or Document Horizontal 
Scroll. 


You can add both or just one. 


Adding Local Scroll Bars 


When you add local scroll bars to a document object, the scroll 
bars on the application window disappear unless there are 
other scrollable document objects on the screen. 


You must turn on either Horizontal or Vertical Scroll to enable 
the Local Scroll Bars option. 


You cannot use Scroll By Page on document objects with local 
scroll bars. Also, Hide Scroll Bars does not hide local scroll 
bars. 


You can scroll document objects with local scroll bars using a 


Scroll All Documents to Top action, but not using Scroll Up, 
Scroll Down, or Scroll to Top actions. 


Adding Local @ To add local scroll bars: 
Scroll Bars 
1. Turn on Horizontal or Vertical Scroll, or both. 


2. Choose Document Local Scroll. 
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have an application name, a topic (basic data grouping), and 
an item (specific data within the topic) defined. For the exact 
syntax, refer to the documentation of the application from 
which you are requesting data. For a more complete descrip- 
tion of DDE and examples, see Chapter 12: Using Dynamic 
Data Exchange. 


@ To define a DDE Request: 


1. Type in the server application name, topic, and item. The 
application name is limited to 32 characters. The topic 
and item cannot exceed 255 characters each. 


or 


= Switch to the server application and copy the data to 
the Clipboard. The application must support the Link 
format. If there is data in the Clipboard in the Link 
format, the Paste Link button is enabled; otherwise, it 
is dimmed. 


= Switch back to LightShip. 


= Choose the Paste Link button and LightShip fills out 
the application, topic, and item for you. 


2. Turn on Auto Start Program to start the server application 
when the DDE Data Request is issued, if it is not already 
running. 


3. Type the command to start the server application. 


Fully specify the pathname of the server application if it is 
not defined by the DOS Path command. You might want 
to define a global variable in LS.INI to specify a pathname 
for the application. 


Fully specify the pathname of the file if it is not defined by 


the DOS Path command or if you do not specify its path in 
the Startup Directory text box. 
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Scroll By Page only affects document objects that use the 
application window scroll bars; it does not affect documents 
with local scroll bars. 

@ To turn on Scroll By Page: 


Choose Options Scroll By Page. 


Anchoring Data to the Document Object 


You can anchor lines of text to the top and bottom of the doc- 
ument object to prevent scrolling beyond a particular point. 
You set a point at the top-left or bottom-right corners of the 
document object. As long as the setting is on, you cannot 
move beyond the point you set. These settings affect both the 
Author and Browse levels. 


© To anchor the first line of data to the top-left of the 
document: 


1. Select the document object. 


2. Scroll it until the appropriate lines of data are at the top of 
the document object. 


3. Choose Document Top-left Corner. 
@ To reset the Top-left Corner: 
Turn it off and on again. 


@ To anchor the last line of data to the bottom-left of 
the document object: 


1. Scroll the document down to the last line of data you 
want to display. 


2. Choose Document Bottom-right Corner. 


Entering Data 
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Creating a User-Entry Document Object 


At the Author level, you can use hidden user-entry document 
objects to create customized lists for selecting data in Point 
mode, such as lists of values to assign to variables or chart 
labels. At the Browse level, you can use user-entry document 
objects as interactive text boxes or to display user selections. 


You can type numbers, strings, variable references, for 
example, @(item), in a user-entry document, or you can leave 
it blank. If you type a variable reference, the value appears at 
both the Author and Browse levels. You can type multiple 
variable references if you only want to display, but not update, 
the values. For information on how to create a document 
object that you can type into at the Browse level, see "Creating 
an Interactive Document." 


When you choose Document Source User Entry, the cursor 
becomes a flashing vertical bar in the document object. 


@ To enter data in a user-entry document object: 
1. Type the data. 


You can use all the edit keys you normally use when you 
enter text in a text box. For more information on edit 
keys, see Chapter 1: Getting Started. 


= Press CTRL+ENTER to start a new line of text. Do not 
press ENTER until you have completed typing every- 
thing you want to enter. 


If you type more lines than can show in the document 
object at once, the list scrolls down automatically as 


you type. 


= Press the UP ARROW, DOWN ARROW, or PAGE keys to scroll 
through the text. 
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Choosing a Font 


The term font describes a specific set of characters in a particu- 
lar typeface design, for example, Helvetica. Font size refers to 
the height of the characters and is usually measured in points, 
for example, 10 point type. Font styles refer to the way a font 
looks, for example, normal, bold, underline, italic. 


When you installed Windows, the Setup program installed cer- 
tain fonts automatically based on your choice of graphics 
adapter and printer(s). For information on how to remove or 
add fonts, refer to the Microsoft Windows User’s Guide. 


You can change the font of a document object, but you can 
only assign one font for each object. If you want different fonts 
for column headers, for example, create separate document 
objects. 
© To choose a font: 
1. Select the document object. 
2. Choose Document Font or press F6. 

The dialog box shown in Figure 4-15 appears. The fonts 


installed in Windows are listed in the Text Font dialog 
box. 


@ To list only monospaced screen fonts: 
Turn on the Fixed Pitch check box. 


For document objects laid out with columns, we 
recommend leaving the Fixed Pitch check box on be- 
cause sometimes characters in proportional type 
overlap and do not display properly. 
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@ To create a customized list: 


1. Create a document object and select User Entry as the 
source. 


2. Type a list of numbers or strings. 
3. Goto Point mode and select the list. 


For the example shown, you would select the chart and 
then choose Chart Labels to get to Point mode. 


LightShip: Point to Chart Labels 


Gross Sales 

Cost Of Goods Sold 
Sales Comrissicns 
Other Expenses 


Net Total Sales 


Figure 4-8 Selecting from a List in Point Mode 


4. Select the values you want and choose OK!. The labels are 
displayed on the chart. 
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5. Select the style(s) you want. 


6. Choose OK. 


Formatting a Document Object 


To format numbers and text in a document object, you must 
first create a format object. You use format objects to: 


= Justify text and numbers 
= Format numbers (for example, $1,000.00) 
= Define and color variances in the data 


What is a Format Object? 


A format object defines a set of attributes that you can apply to 
numbers or text in document objects. For example, a format 
object could format numbers to be left-aligned, with dollar 
signs, and two decimal places. Format objects only affect 
document objects with Document Layout Columns on. 


You select the data to format in Point mode. When None is on 
in the Document Column Delimiter menu, LightShip 
interprets each row as being one wide column. When you 
select data in Point mode, it highlights one character at a time. 
Remember to select extra spaces to allow for prefixes and 
suffixes in the formatted data. 


The data you select is formatted according to the settings on 
the Format menu. If you see asterisks (****) in the document 
object, it means that there is not enough space to display the 
data as it is formatted. Try increasing the selection range in 
Point mode and changing the settings on the Numeric Format 
dialog box; for example, reduce the number of decimal digits 
or erase a prefix or suffix symbol. 


Example 
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@ To create an interactive document: 


1. Create a document object and select User Entry as the 
source. 


2. Type one simple variable reference (for example, 


@(item)). 
4. Turn on Document User Edit. 


4. (Optional) Turn on Document Numeric Required, to re- 
strict data entry to numbers. 


If you choose this option, your application displays an 
error message if you type in non-numeric data. 


5. (Optional) Specify the layout using the Document Layout 
menu. 


This allows you to control how data in the document 
appears; for example, Word Wrap is an option. For more 
information, see "Defining the Layout." 


For example, Figure 4-10 shows a screen with two document 
objects, a user-edit document object and a document object 
that displays a text file. When you type a filename into the 
user-edit document, that file displays in the other document 
object. 


1. Use Special Variables to define a variable called /ile. 


2. Create a user-entry document at the Author level and type 
a variable reference in it as shown: 


4. Choose Document User Edit. 
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3. Drag or click the mouse to create the format object, as 


shown in Figure 4-16. 
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Figure 4-16 Creating a Format Object 
4. Choose Format Destination. 


The screen changes to Point mode so that you can select 
the data you want to format (see Figure 4-17). 
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Figure 4-11 Editing User-Entry Data 
Click on the point at which you want to start typing. 
The cursor changes to a flashing vertical bar. If you press 
a key without clicking in the document first, it deletes all 
highlighted text. To bring it back (before you do anything 
else), press the ESC key, then start again. 
Type into the document. 


When you are finished typing, press ENTER. 


Changing the Data Source 


1. 


To change the data source of a document object: 
Select the document object. 


Choose Document Source, press F2, or double-click on the 
document object. 


The Document Source menu appears (see Figure 4-2). 


For more information, see the section for the appropriate 
document source in "Creating Document Objects." 
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cS Hint 


If you are formatting a document object that is going to scroll, 
scrolling will be faster if you select an entire row or an entire 
column to format. 


2. When you are finished, choose OK! on the menu bar. 
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Figure 4-19 A Formatted Document Object 


Formatting Numbers 


To format numbers: 


Choose View Show Hidden Objects. 


Select the format object. 


Choose Format Numeric Format, press F2, or double-click 


on the format object. 


A dialog box appears. 


Specifying 
Column 
Delimiters 
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= Choose Fill for data to wrap to the next line depend- 
ing on the size of the document object. Fill ignores 
line feeds and carriage returns in the source docu- 
ment object. Two carriage returns create a new 


paragraph. 


Defining Columns 


When you first display columns of data in a document object, 
the columns may not be spaced or aligned correctly. You can 
specify the column width(s) and the character(s) that mark the 
division between columns (called the column delimiter). 
LightShip uses characters in the source data to delimit 
columns. For example, most DDE data uses tab characters to 
mark the column divisions. You can specify tab characters, 
commas, or spaces as column delimiters. LightShip creates a 
new column whenever it encounters the delimiter character. 


The column delimiter and widths that you specify affect the 
way data appears in the document object. They also affect the 
width of the selection range (the area that highlights) when 
you select data in Point mode. For more information about 
Point mode, see Chapter 3: Objects, Tools, and Modes. 


The way you specify columns in a document object affects how 
you select data in Point mode. When you specify a column 
delimiter other than None, data in Point mode is highlighted 
by column; the widths of the selection ranges are defined by 
the numbers that you enter in the Document Column Width 
dialog box. When you specify no delimiter (None), it does not 
change the way the data appears on the screen; it only affects 
Point mode, where data highlights one character at a time. 
When None is on, LightShip assumes each row is one wide 
column (or one cell) and you cannot enter column widths in 
the Document Column Width dialog box. 
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Figure 4-34 Defining Special Values 


3. Click in the OUTNA text box and type the output value. 
You can only have one output value. For example: 


NA 
4. Choose OK. 


If your document looked like the one on the left before, it 
displays the output values you defined, as shown: 
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Text, Draw Objects, and Images 


This chapter explains how to enter text, create simple draw 
objects, and import images into your application. 


What Is a Text Object? 


You display simple text on a screen by creating a text object. 
Use text objects to display small amounts of text, such as titles 
or headers. To display larger amounts of text, use document 
objects. Figure 5-1 shows an organizational chart that displays 
employee names in text objects. 


EVP - 
Finance 


Figure 5-1 Text Objects 


LightShip User’s Guide 


5-12 


Coloring a Draw Object 

© To change the color of a draw object: 
1. Select the object. 

2. Choose Draw Color or press F5. 


A dialog box appears. 


Draw Color 


Figure 5-9 Choosing a Color 
3. Select the color you want. 


4. Choose OK. 


Outlining or Filling Draw Objects 

Rectangles, round rectangles, and ellipses are initially solid. 
@ To change a solid object to an outline: 

1. Select the object. 


2. Choose Border Thin, Medium, Thick, or Other to define 
your own line width. 


When you choose Other, a dialog box appears. 
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an application that uses DDE. For more information, 


Choose DDE Data Request to display an image from 
see "Displaying an Image from a DDE Request. 


Displaying a PCX or BMP File 


When you choose PCX File or BMP File from the Image Source 


menu, the Image Source File dialog box appears. 


Filename text box or double-click 


on a filename in the Files list box. 


Type a filename in the 


1. 


Choose OK. 
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Figure 5-14 Displaying a BMP File 
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Changing a Color 


5-14 


16-color display adapters display 16 solid colors and 32 
dithered (mixed) colors. When you select a color on the 
Palette dialog box, the color you select displays in the Color 
and Solid boxes on the right, as shown in Figure 5-11. If you 
have a 16-color monitor, when you select a dithered color, you 
will see the dithered color displayed in the Color box and the 
solid color displayed in the Solid box. One of the colors will 
appear on the Color dialog boxes for the different objects, 
depending on the type of object you are coloring. If you are 
coloring foreground text or a line, the solid color will be dis- 
played. If you are coloring an area or a background, (and a 
dithered color is selected) the dithered color will be displayed. 


Use the scroll bars in the lower-left corner of the Palette dialog 
box to change the amount of red, green, and blue in each 
color. When the scroll box is all the way to the right, the 
amount of red, green, or blue is at its maximum. When the 
scroll box is all the way to the left, the color is eliminated. 


If the OK button becomes unavailable, it means you have 
entered an invalid number in one of the RGB text boxes. 


@ To change a color on the palette: 
1. Choose Options Palette or press SHIFT+F5. 


A dialog box appears. 


Palette 


Figure 5-11 Changing the Palette 
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Displaying an Image from a DDE Request 


When you choose DDE Data Request from the Image Source 
menu, the dialog box shown in Figure 5-16 appears. 


Image DDE Data Request 
a ee [e OO OOOO O E) 


Topic: | e:\excel\chart4_xic 


item: 


Paste Link 3 


><] Auto Start Program 


Command Line: | excel chart4_xic 
Startup Directory 


Figure 5-16 Importing an Image with a DDE Data Request 


The program to which you send the DDE Request is called the 
server or server application. It must support the CF_BITMAP 
format. 


The exact form of the DDE Request will vary, depending on 
the application. However, all applications using DDE must 
have an application name, a topic (basic data grouping), and 
an item (specific data within the topic) defined. For the exact 
syntax, refer to the documentation of the application from 
which you are getting the image. For more complete infor- 
mation about DDE, see Chapter 12: Using Dynamic Data 
Exchange. 


You might want to define a global variable in LS.INI to specify 
a pathname for the application from which you are requesting 
data. 
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Figure 5-12 Displaying Images 


When you create or select an image, the Image menu appears 
on the menu bar. Use this menu to: 


= Change the source of the image. 

= Change the size and scale of the image or the image object 
window. 

= Make a copy of the palette for that image. 


By default, an image object is created in the same size as the 
original image. Use the settings on the Image menu to change 
the size of an image object. 


When Images are Updated 


LightShip displays the most current image in an image object 
whenever you open a screen. LightShip also updates image 
objects automatically as described below. In addition to 
automatic updates, you can manually update image objects by 
executing a Calculate Now command. 
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Figure 5-17 Importing a DDE Bitmap 
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Changing an Image Source 


E 
1. 


To change the source of the image: 
Select the image object. 


Choose Image Source, double-click on the object, or press 
F2. 


The Image Source menu appears. 


Choose the source. 
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Figure 5-13 Creating an Image Object 


4. Choose one of the menu items. 
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The Palette option is not available unless you turn on 
Image Save Palette. To read about changing the 
image’s palette, see "Coloring an Image Object." 


Choose PCX File to display a PCX image. For more 
information, see the next section "Displaying a PCX or 
BMP File." 


Choose BMP File to display a BMP image. For more 
information, see the next section "Displaying a PCX or 
BMP File." 


Choose Clipboard to display a Clipboard image. For 
more information, see "Displaying an Image from the 
Clipboard." 


If the Clipboard option is not available, it means there 
is no bitmap on the Clipboard. Cutting or copying a 
bitmap image from any Windows application saves it 
on the Clipboard. 


Resetting the 
Palette 


cS Hint 
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@ To return the colors to the way they were when you 
opened the dialog box: 


Choose the Default button. 
@ To return to the original colors of the image: 


Turn Save Palette off and choose OK when LightShip asks 
if it is OK to delete the saved palette. 


Changing the Size and Scale of an Image 


Unless you change the settings on the Image menu before 
creating an image, it is created in the same size as the original. 
You can change the size and scale of images in the following 


ways: 
= Resize the image and the image object window together. 


= Resize the image independently of the image object win- 
dow. 


= Resize the image object window independently of the 


image. 


LightShip’s performance is best when an image is 1:1 in scale. 


i 


Resizing an Image and the Window Together 


There are two ways to resize the image and the image object 
window together. You can type in numbers for the scale or re- 
size the image by dragging it with the mouse. If you drag it, it 
might not resize proportionately. 
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Displaying an Image from the Clipboard 


Clipboard images must be in CF_DIB or CF_BITMAP format. 
CF_DIB is a device-independent format. CF BITMAP is the 
Clipboard bitmap format. If a CF_BITMAP image has palette 
information stored with it (in CF_PALETTE format), LightShip 
also uses the palette information. 


When you choose Clipboard from the Image Source menu, the 
image appears in the image object. 
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Figure 5-15 Displaying a Clipboard Image 
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Resizing the 
Image Only 


Resizing the 
Window Only 
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Resizing an Image and the Window Separately 


To change the size of the image and leave the image 
object window the same size: 


Select the image object. 
Turn off both Fit Object to Image and Fit Image to Object. 


Choose Image Scaling and type in the numbers for the 
scale. 


Choose OK. 

To change the size of the image object window and 
leave the image the same size: 

Select the image object. 

Turn off both Fit Object to Image and Fit Image to Object. 


Resize the image object by dragging any corner with the 
mouse. 
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Defining a DDE 

Request 1. Type in the server application name, topic, and item. The 
application name is limited to 32 characters. The topic 
and item cannot exceed 255 characters each. 


Or 


= Goto the server application and copy the data to the 
Clipboard. The application must support the Link 
format. If there is data on the Clipboard in the Link 
format, the Paste Link button is available; otherwise, 
it is dimmed. 


= Choose the Paste Link button and LightShip fills out 
the application, topic, and item for you. 


2. Turn on Auto Start Program to start the server application 
when the DDE Data Request is issued, if it is not already 
running. 


3. Type the command to start the server application. 


= Fully specify the pathname of the server application if 
it is not defined by the DOS Path command or if you 
do not specify its path in the Startup Directory text 
box. 


= Fully specify the pathname of the file if it is not de- 
fined by the DOS Path command or if you do not 
specify its path in the Startup Directory text box. 


4. (Optional) To start the server application in a different di- 
rectory than the current one, type the drive and directory 
in the Startup Directory text box. 


This lets you use files in that directory without specifying 
a path. The current working directory remains the same. 


5. Choose OK. 


The image appears on the screen. Figure 5-17 shows an 
Excel chart displayed with a DDE Data Request. 


Justifying Text 
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4. Type in the text. 


= #§ Press CTRL+ENTER to start a new line. Do not press 
ENTER until you have finished typing. 


If you press ENTER by mistake, double-click on the ob- 
ject to start typing again. The text is highlighted. If 
you press a key without clicking in the document 
first, it deletes all highlighted text. To bring it back 


(before you do anything else), press the Esc key, then 
Start again. 


5. Choose OK. 
The text appears in the text object. If all the text does not 
show, resize the text object. 

@ To justify text: 

1. Select the text object. 


2. Choose Text Justification Left, Center, or Right. 


Coloring a Text Object 


You color text and its background with different colors. All of 
the Text colors are solid, but some of the Background colors 
might be dithered, that is, made up of different colored dots. 
Text shows up more clearly when you place it on a solid 
background. If you are unsure which colors are solid and 
which are dithered, choose Options Palette. The Palette dialog 
box shows whether a color is solid or dithered in the Solid 
and Color boxes. 
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Coloring an Image 


Coloring an Image Object 


There are 256 colors possible on a LightShip screen if you 
have a 256-color display adapter. Sixteen colors are used by 
Windows and 48 colors are used by the LightShip default 
palette for draw objects, text colors, and so on. This leaves 
200 colors for images. 


When you display an image, LightShip attempts to match each 
color to a color on the palette. If the color is not on the 
palette, LightShip adds it. If the palette is full, LightShip uses 
the nearest available color. 
You can change the color of an image within LightShip by as- 
sociating a particular palette with the image and then changing 
the palette. This saves you from having to use a paint program 
to change colors. 
@ To change the color of an image: 
1. Select the image object. 
2. Choose Save Palette. 

This makes a copy of the palette for that image. 
3. Choose Image Source Palette. 


4. Select a color you want to change. 


5. Drag the scroll box or type a number from zero to 255 in 
any or all of the RGB boxes. 


6. After you are finished changing all the colors, choose OK. 
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© To choose a font: 
1. Select the text object. 
2. Choose Text Font or press F6. 


A dialog box appears. 


Text Font 


><] Normal 


[_] Bold 


[C] Italic 
[_] Printer Fonts ize: C] Underline 
[L] Fixed Pitch CI Strikeout 
Text Sample: 


Figure 5-4 Choosing a Font 


3. Choose the font, point size, and style. 


4. Choose OK. 


Creating Shadowed Text 
@ To make text appear three-dimensional: 
1. Create a text object. 


2. Color it and select a font. 
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Resizing with the 
Mouse 


Typing in the 
Scale Manually 


Resetting the 
Scale 
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To resize the image by dragging it with the mouse: 
Select the image object. 
Turn on Fit Image to Object. 


Resize the image object window by dragging any corner. 


To type in the scale manually: 
Select the image object. 
Leave on Fit Object to Image and choose Image Scaling. 


A dialog box appears. 


Image Scaling 


Horizontal: 
Vertical: 


Figure 5-18 Scaling an Image 


Type in the numbers for the Horizontal and the Vertical 
axes. 


The scale is determined relative to the size of the original 
image in the source file. 


Choose OK. 


To reset the scale to the default setting: 


Choose Default to reset the Horizontal and Vertical scale 
to 1:1. 
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Changing Text 
@ To change the text: 
1. Select the text object. 


2. Choose Text Text, press F2, or double-click on the text 
object. 


A dialog box appears with the text highlighted. 


Pilot Executive Software 


Figure 5-7 Editing Text 
3. To overwrite the text, just start typing. 
To insert text, click on the insertion point before you start 
typing or you will lose all the text. If you do accidently 
lose your text, press ESC immediately and start again by 


pressing F2. 


= Press CTRL+ENTER to start a new line. Do not press 
ENTER until you have finished typing. 
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The Text Menu When you create or select a text object, the Text menu appears 
on the menu bar. The Text menu allows you to: 


Change the text 

Justify the text 

Color the text and background 
Choose a font, point size, and style 


Creating a Text Object 


You can type text or a variable reference, for example, 
@(item), in a text object. If you type a variable reference, the 
value of the variable is displayed at both the Author and 
Browse levels. If the variable has no value, the text object ap- 
pears blank. 

You can use all the edit keys you normally use when you enter 
text in a text box. For more information on edit keys, see 
Chapter 1: Getting Started. 

@ To create a text object: 

1. Choose Tool Text. 

2. Drag or click the mouse to create the text object. 


3. Choose Text Text, press F2, or double-click on the object. 


A dialog box appears. 


Pilot Executive Software 


Figure 5-2 Editing Text 


The Draw Menu 
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When you create or select a draw object, the Draw menu ap- 
pears on the menu bar. This menu allows you to: 


= Choose the draw object shape. 


m Fill or outline the object. 
= Color the object. 


Creating a Draw Object 

You can create a draw object either from the Tool menu or 
from a draw tool icon on the Toolbox. You can constrain 
draw objects when creating them by turning on the grid. Con- 
straining draw objects allows you to draw straight lines, 
squares, and circles. 

@ To constrain draw objects to the grid: 


Turn on View Grid Snap or hold down the cTRL key before 
drawing. 


Creating Draw Objects from the Toolbox 
Use the Toolbox when you want to create multiple objects. 
@ To create draw objects from the Toolbox: 
1. Choose Tool Toolbox. 
The Toolbox appears on the screen. 
2. Select the Draw tool (the pencil icon). 


The draw tool icons appear on the right side of the Tool- 
box. 
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Coloring Text @ To color text: 
1. Select the text object. 
2. Choose Text Color or press F5. 


A dialog box appears. 


Text Color 


Figure 5-3 Coloring Text 
3. Select a text color. 
4. Select a background color or select Transparent if you 
want the color of whatever is underneath the text object 


to show through the background. 


5. Choose OK. 


Choosing a Font 


The Text Font dialog box is the same as the one used for 
document object font selection. See "Choosing a Font" in 
Chapter 4: Displaying Data for more information about 
choosing fonts. 


5-4 


Drawing a 
Rectangle or an 
Ellipse 


Drawing a Line 


Drawing a 
Polygon 
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Creating a Draw Object from the Tool Menu 


Rectangles are solid by default. 


iP 


To draw a rectangle, round rectangle, or an ellipse: 
Choose Tool Draw. 


Choose Draw Shape Rectangle, Draw Shape Round 
Rectangle, or Draw Shape Ellipse. 


Drag or click the mouse to create the object. 


To draw a line: 

Choose Tool Draw. 

Choose Draw Shape Line. 

Click and drag the mouse to draw the line. 


Click the mouse to end the line. 


To draw a polygon: 
Choose Tool Draw. 
Choose Draw Shape Polygon. 


Click and drag the mouse to draw the first line of the 
polygon. 


Click the mouse when you want the line to go in another 
direction. 


Double-click the mouse to end the polygon. 
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Duplicate the text object. 
Drag the copy away from the original. 


Change the color of one of the objects and make the 
background transparent. 


Drag the text with the transparent background so that it is 
in front of the other text object. 


Figure 5-5 Shadowed Text 


To make text appear raised: 
Create three copies of a text object. 


Make one of the copies the same color as the screen back- 
ground and the other two different colors. 


Make all the backgrounds transparent. 


Position them so the object that matches the color of the 
background is outlined by the other two objects. 


256-Color Display 
Adapter 


16-Color Display 
Adapter 
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Other Thickness 
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Figure 5-10 Changing the Width of a Line 


1. Type a number from one to 48 to represent the line 
thickness. 


The lower the number, the thinner the line. 


2. Choose OK. 


Changing the Color Palette 


There are 48 colors available for objects and screen color on 
the Palette dialog box. You can modify the palette, which 
changes the colors available for all objects. The palette is 
saved with the screen. 


LightShip uses a Red (R), Green (G), and Blue (B) color 
palette. You can display the RGB numbers for all the colors on 
the palette by choosing Palette List in the Debug window. 


If your display adapter supports 256 colors, you can display 
256 colors as solid, if Options Optimize Palette is turned on. 
This uses the best colors possible for the installed display de- 
vice driver. 


If you are developing applications using a 16-color display 
adapter and you want to keep the colors the same even if 
displayed on a 256-color display adapter, leave Options 
Optimize Palette off. 
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If you press ENTER by mistake, double-click on the ob- 
ject to start typing again. 


4. Choose OK. 


What is a Draw Object? 


A draw object is a simple shape you draw on the screen. 
Figure 5-8 shows a screen with draw objects. 
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Figure 5-8 Draw Objects 


You can draw the following types of objects: 


= Rectangles 

= Round Rectangles 
= Lines 

= Ellipses 

= Polygons 


Resetting the 
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Select the color. 


Drag the scroll box or type a number from zero to 255 in 
any or all of the RGB boxes. 


The color you are creating displays in the Color and Solid 
boxes in the lower-right corner of the dialog box. 


Choose OK. 
To return the colors to the way they were when you 
opened the dialog box: 


Choose the Default button. 


What is an Image Object? 


You display a graphic image by creating an image object and 
then specifying the source of the image. An image object can 
display an image from: 


A PCX file, which is a type of graphic file format. 

A BMP file, which is a bitmap format created by Windows 
Paint. 

The Clipboard, which must be in CF_DIB or CF_BITMAP 
format. 

A DDE Request, which must conform to the CF_BITMAP 
format. 


Clipboard images are saved with the screen, which makes 
them faster to display. PCX files, BMP files, and DDE Data 
Requests are loaded into the image object each time the screen 
is displayed. 


Figure 5-12 shows a screen with image objects used as icons. 


5-15 


LightShip User’s Guide 


Rectangle 


Round Rectangle 
Line 
Ellipse 


Polygon 


R 
f 
pæ 


| | Aon 


3. Select the tool that you want. 
= Ifyou select the rectangle, round rectangle, or ellipse, 
every time you click or drag the mouse, you will 
create another object of that type. 


= Ifyou select the line tool, click to start the line, drag 
to draw the line, and then click to end the line. 


= If you select the polygon tool, click the mouse every 
time you want to end a line in the polygon. Double- 
click to end the polygon. 
@ To leave Create mode: 
Select the pointer at the top of the Toolbox. 


@ To close the Toolbox: 


Double-click on the Toolbox title bar or choose Tool 
Toolbox again. 
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DDE Requests 


PCX and BMP 
Files 
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When Calculation Automatic is on, image objects whose 
source is a DDE Request are updated when: 


= Source data changes. 
= ÀA literal or variable reference in a DDE Request dialog box 
changes. 


When Calculation Manual is on, if you make a literal change to 
a DDE Request dialog box, you are prompted to execute the 
request. 


Image objects whose source is a PCX or BMP file are always 
updated when you make a literal change to the filename. If 
Calculation Automatic is on, and a variable reference in the 
filename changes, the image object is also updated. 


Creating an Image Object 
@ To create an image object: 
1. Choose Tool Image. 


2. Drag or click the mouse to create the object in which the 
image will appear. 


3. Choose Image Source, press F2, or double-click on the 
image object. 


The Image Source menu appears, as shown in Figure 5-13. 
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CHAPTER 6 
CREATING CHARTS 


This chapter describes how to chart the data in document 
objects. 


What is a Chart Object? 


LightShip displays charts in chart objects. Chart objects are 
dynamically linked with document objects so that you see 
changes in data immediately. 


Regional Sales 


Be Ce 
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Figure 6-1 LightShip Charts 
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Figure 6-22 Displaying a Title 


Displaying Labels 


Labels are the text associated with each data point. They are 
displayed along the category axis, which is usually horizontal, 
and are called category labels to distinguish them from the 
numeric labels that are displayed along the numeric axis. Like 
the chart title, you add category labels to a chart by selecting 
text from a document object in Point mode. 


@ To display labels: 
1. Select the chart. 


Choose Chart Labels. 


N 


The screen changes to Point mode. 
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Figure 6-18 A Horizontal Chart 


Displaying Legends 

Legends identify the data that is charted. You select legends 
from a document object in Point mode. If you are selecting 
legends that are printed across a row, you must select each 
legend individually, as shown in Figure 6-19. 

You can suppress a legend by selecting a blank space. For 
example, if you have three data series, and you want to display 
legends for the first and third data series, you could select a 
blank space for the second legend and it would not appear. 
Legends display in a column. To display labels in a row, create 
draw objects to represent the color swatch and text objects to 
represent the legend. 

@ To select legends: 

1. Select the chart. 

2. Choose Chart Legends. 


The screen changes to Point mode. 
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Category Labels 
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Figure 6-24 Displaying Labels 


Displaying Labels Selectively 


Labels are displayed for each data point by default. However, 
you can control how often labels are displayed, where they 
start, and whether or not they appear next to their corre- 
sponding data point. 


The Label Interval setting on the Chart Category Scale dialog 
box controls how often labels appear. When the Label Interval 
is one, every label that you selected in Point mode appears 
next to its corresponding data point. You can display labels 
only at certain intervals. For example, you can display a label 
on every other data point by changing the Label Interval 
setting to two. 


If you display labels at intervals other than one, you can 
control whether labels appear next to their corresponding 
data point (and skip the ones in between) or you can display 
every label you selected (without skipping any). You control 
this by using the Skip check box. For example, if you are dis- 
playing a label at every fourth data point, when Skip is on you 
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Displaying a Title 
You add a title to a chart by selecting text from a document 
object in Point mode. If no document has the text you want 


for a title, create a new one and use the User Entry command 


to enter the text you want. Then make the document object 
hidden. 


BM To add a title: 
1. Select the chart. 
2. Choose Chart Title. 


The screen changes to Point mode. 


LightShip: Point to Chart Title 


SS Wet To 


3. Select one line of text for the title. 
The text cannot cross columns. 


4. Choose OK! on the menu bar. 
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@ To select the data point on which the first label 
appears: 


Type a number into the Label Start box. For example, 
if you type five, the first label will appear next to the 
fifth data point (if the Skip option is off). If you turn 
Skip on, the fifth label will appear next to the fifth 
data point. 


Example The following example illustrates how Label Start and Label 
Interval interact when the Skip option is off. We selected data 
from a text file to create a chart of housing prices in Boston. 


LightShip: Point to 1st Chart Vata 
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ist quarter 2nd quarter Jrd quarter 4th quarter 


This data file contains about 10 years worth of quarterly data. 
The first data point is not available. 


= We selected the years 1982-1990 from the column on the 
left side of the text file for our labels. 


= We set the Label Interval to four because we only wanted 
to display one label (the year) for each year. 


= We set the Label Start to four because we wanted the first 


label to start on the first quarter of the second year (the 
fourth data point). 
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bightShip: Point to Chart labels 


Select the labels in the order in which you want them to 
appear. 


If Document Column Delimiter None is on and you want 


to select multiple labels across a row, you must select each 
label individually. 


Choose OK! on the menu bar. 
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Changing a 
Numeric Scale 
Setting 


Setting Low and 
High Values 
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Where major numbers, tickmarks, and grid lines appear 
Where minor tickmarks and grid lines appear 

Where the crosses line appears 

Numeric formatting 


LightShip calculates all of these settings automatically based 
on the numbers and the size of the chart, but you can change 
any of them. 

@ To change a numeric scale setting: 


Choose Chart Numeric Scale. 


A dialog box appears. 


Chart Numeric Scale 


Auto 


Xx] Low: 
CX] High: 


x] Major: 
CX] Minor: 
[xX] Crosses: 


Figure 6-28 Setting the Numeric Scale 
When the settings on the left are turned on, the text boxes to 
their right display the calculated settings and are not available 


for data entry. To enter your own value, turn off the check 
box. You will then be able to type a value. 


@ To enter a low value: 


Type a number in the Low box. 
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display every fourth label. When Skip is off you display each 
label sequentially at every fourth data point. 


You can also control where labels begin by using the Label 
Start option. This option controls which data point the first 
label is displayed next to. The label that appears is controlled 
by the Skip option. 


Changing a Label @ To change a label interval or start: 
Interval or Label 
Start Choose Chart Category Scale. 


A dialog box appears. 


Chart Category Scale 


Label Interval: 


Group Interval: 


ÒI Between 


C] Reverse 


1 

Label Start: 

a LJ Skip 
1 
1 


Group Start: 


Figure 6-25 Specifying Label Intervals 
@ To change the label interval: 
Type a number in the Label Interval box. For exam- 
ple, to display a label on every other point, set the 
label interval to two. 


@ To make the labels appear next to their 
associated data point: 


Turn Skip on. 
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Specifying the 
Crosses Line 


5. Choose OK. 


Figure 6-29 shows a chart with both major and minor tick- 
marks, as well as a major numeric grid. The major tickmarks 
are set to 20,000 and the minor tickmarks are set to 10,000. 
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Figure 6-29 Numeric Major and Minor Tickmarks and Major Grid 


The crosses line has a number that represents a base line for 


by default. 


On vertical charts, if you set the crosses line to a number other 


than zero, data points greater than the crosses line are drawn 
above it and data points less than the crosses line are drawn 
below it. 


On horizontal charts, if you set the crosses line to a number 
other than zero, data points greater than the crosses line are 
drawn to the right and data points less than the crosses line 
are drawn to the left. 


the data points you are charting. The crosses line is set to zero 
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a We left the Skip option off because we wanted to show 
every year (not every fourth year). Figure 6-27 shows the 
chart. 
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Figure 6-27 Displaying Labels at Intervals 


Setting the Scale 

Charts have two kinds of scales, numeric and category. The 
category scale is made up of text labels, such as time or 
product names. The numeric scale is linear. For vertical 


charts, the numeric scale is usually along the left vertical axis 
and the category scale is along the bottom horizontal axis. 


Setting the Numeric Scale 
The numeric scale settings affect: 


= The lowest value charted 
= The highest value charted 
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Reversing the 
Scale 


You can reverse the numeric scale so that it goes from the 
highest number to the lowest number. 


@ To reverse the numeric scale: 


Turn on the Reverse check box on the Chart Numeric 
Scale dialog box. 


setting the Category Scale 

The category scale affects: 

= Where and how the category labels are displayed. For 
more information about how labels are displayed, see 
"Displaying Labels." 

= Where and how grid lines and tickmarks are displayed. 


This section discusses how to display grid lines and tickmarks 
along the category scale. 


@ To change a category scale setting: 
Choose Chart Category Scale. 


A dialog box appears. 


Chart Category Scale 


Label Interval: 


Label Start: E Skip 


ÈJ Between 
C] Reverse 


Group Start: 


1 
1 
Group Interval: Poo 
1 


Figure 6-31 Changing the Category Scale Settings 


Specifying Major 
and Minor 
Settings 
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@ To enter a high value: 

Type a number in the High box. 
The Major setting controls where the numbers are displayed 
along the numeric scale. It also controls where the major 
tickmarks and grid lines are displayed, if they are colored. 
The Minor setting does not display a number, but it allows you 
to display a second set of tickmarks and grid lines. By default, 


the Minor setting is the same as the Major setting. Minor tick- 
marks and grid lines must also be colored, if they are to dis- 


play. 
@ To specify the major setting: 
Type a number in the Major text box. 
@ To specify major tickmarks and grid lines: 
1. Select the chart. 
2. Choose Chart Color or press F5. 


3. Select Numeric Major Inside Ticks, Numeric Major 
Outside Ticks, or Numeric Major Grid. 


4. Selecta color. 

5. Choose OK. 

@ To specify minor tickmarks and grid lines: 
1. Select the chart. 

2. Choose Chart Color or press F5. 


4. Select Numeric Minor Inside Ticks, Numeric Minor 
Outside Ticks, or Numeric Minor Grid. 


4. Select a color. 
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This number corresponds to the data point at which the 
tickmark or grid line will appear. 


Specifying an @ To specify an interval: 

Interval 
Type a number in the Label Interval or Group Interval box 
in the Chart Category Scale dialog box. 


The number represents the interval at which the tickmarks 
or grid lines will appear. 


Where Grids and By default, grid lines and tickmarks appear in the middle of a 
Ticks Appear on data point. 
the Data Point 
@ To make a group grid or group tickmark display 
between data points: 


Turn on Between. 


Example of Group The following example illustrates how Group Start and Group 
Start and Group Interval work. This chart adds an outside tickmark and a grid 
Interval line for every year on the chart shown in Figure 6-33. 


This chart has both Group Start and Group Interval set to four. 
As long as the grid and tickmarks are colored, this setting 
draws a grid line and a tickmark starting at the fourth data 
point and draws a grid line every fourth data point after that. 
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If you reverse the numeric scale, data points greater that the 
crosses line are drawn below it, and data points less than the 
crosses line are drawn above it. 

@ To enter a number for the crosses line: 


Type a number in the Crosses text box in the Chart 
Numeric Scale dialog box. 


Figure 6-30 shows a chart with the crosses line set to 100,000. 
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@ To change the way numbers are formatted on the 
numeric scale: 


Choose the Format button on the Chart Numeric Scale 
dialog box. 


The Numeric Format dialog box appears. This dialog box 
is the same as the one used for formatting numbers in 
document objects. For information on formatting num- 
bers, see Chapter 4: Displaying Data. 
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Chart Colors: 


Background Area 
Plot Area 

Frame 

Title 

Legend 

Outline 

Ist Chart Data 


F nineteen 


Figure 6-34 Selecting Items to Color 
Choose the chart item you want to color. 
Select a color. 


Select Invisible to remove the display of a chart fore- 
ground item. 


The Background colors are available only when you select 
a text chart item so that you can specify a background 
color as well as a text color. Select Transparent to make a 
chart item background transparent so that whatever is 
behind it shows through. 


You can select as many chart items and colors as you want 
before choosing OK. 
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Displaying Grid You display a grid and tickmarks by coloring them. You can 
Lines and display two sets of tickmarks and grid lines on the category 
Tickmarks axis. These are called Zabel and group. Label tickmarks and 


grid lines are controlled by the Label Start and Label Interval 
options on the Category Scale dialog box. Group tickmarks 
and grid lines are controlled by the Group Start and Group 
Interval options on the Category Scale dialog box. 


Category Label Grid 


Category Label Outside 
Tickmarks 


Figure 6-32 Displaying Tickmarks and Grid Lines 


@ To display grid lines and tickmarks: 
1. Choose Chart Color. 


2. Select the grid or tickmark that you want to appear on 
your chart. 


4. Selecta color. 


4. Choose OK. 
Specifying a Start @ To specify where tickmarks or grid lines start: 


1. Type a number in the Label Start or Group Start box in the 
Chart Category Scale dialog box. 
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The Chart Menu 


Plot Area 


Data 


Numeric 
Tickmarks 


Crosses Line 


Legends 
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When you create or select a chart object, the Chart menu 
appears on the menu bar. This menu allows you to: 


Add, change, or delete a data series. 

Enter a title, labels, and legends. 

Change the chart type. 

Specify the numeric and category scales. 

Add tickmarks and grid lines. 

Color the parts of a chart and change the fonts of chart 
text. 


The Parts of a Chart 
Figure 6-2 shows the parts of a chart object. 


Numeric Axis, Title Background Area 


‘igure 6-2 The Parts of a Chart 


Category Axis Labels Category Tickmarks Category Grid Lines 
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Figure 6-33 Adding a Category Group Grid and Category Label 
Outside Tickmarks 


Reversing the You can reverse the category scale so that data points and 
Scale labels display from last to first. 
@ To reverse the category scale: 


Turn on the Reverse check box. 


Coloring a Chart 

For information about coloring specific items in a chart and 
changing the default colors for a chart, see the LightShip 
Reference Guide. 

@ To color the different items of a chart: 


1. Choose Chart Color. 


A dialog box appears. 
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6-4 


Tickmarks Tickmarks are short lines that mark the numeric and category 
scale on an axis. 


Grid Lines Grid lines are dotted lines that appear within the plot area that 
mark the numeric and category scale. 


Chart Types 


LightShip has four types of charts to choose from: bar, line, 
area, and pie. 


Bar Line 


Area Pie 
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Choosing a Font for Chart Text 


@ To choose a font for a text item on a chart: 


1. Choose Chart Font. 


A dialog box appears. 


iS Double-click 
on the chart item to 


Chart Fonts 


Title 
Legend 
Numeric Label 


_ Label 


Figure 6-35 Choosing a Font 


go directly to the 


Fonts dialog box. 


2. Choose the text item whose font you want to change. 

3. Choose OK. 
The Fonts dialog box appears. This dialog box is the same 
as the one used for document object font selection. For 
more information on choosing fonts, see "Choosing a 
Font" in Chapter 4: Displaying Data. 

4. Choose the font, point size, and style. 


5. Choose OK. 
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Figure 6-3 Selecting a Data Series to Chart 
5. Choose OK! on the menu bar. 


The first data series is charted in the object. 


Figure 6-4 The First Data Series is Charted 
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The data that you chart comes from document objects. You 
select the data in Point mode. Each set of data that you select 
to chart is called a data series. Each number in a series is 
called a data point. You can chart up to eight data series in 
one chart. 


The title is the heading at the top of the chart. 


A label is the text associated with each data point. 


The legend identifies the data series being charted. It is dis- 
played with a color key on the chart. 


The plot area is the inner rectangle in which the data is 
charted. 


The background area is the area around the plot area. 


The numeric axis determines the type and range of 
measurement, usually on the vertical axis (y-axis). For 
horizontal charts, the numeric axis is on the horizontal axis 
(x-axis). 


The category axis labels the data being charted, usually along 
the horizontal axis (x-axis). For horizontal charts, the category 
axis is on the vertical axis (y-axis). 


The crosses line has a number that represents a base line for 
the data. By default, it is set to zero and shares the same line 
as the category axis. On default charts, if you set the crosses 
line to a number other than zero, numbers greater than the 
crosses line are charted above it; numbers less than the crosses 
line are charted below it. 
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Figure 6-6 The Second Data Series is Charted 


Changing a Data Series 


When you delete a data series from a chart, the numbers of 
subsequent data series move up in number. For example, if 
you delete the 3rd data series, the 4th data series becomes the 
3rd data series. 


a 
1, 


To change or delete a data series from a chart: 


Choose Chart Data and the number of the series you want 
to change. 


The Point mode screen appears. 

@ To change a data series: 
Change the data items on the Point mode screen by 
using the Undo!, Redo!, or Clear All! options on the 


menu bar. 


You can add more items to the data series by selecting 
them. 
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Creating a Chart 


Because LightShip charts data from document objects, you 
must have at least one document object on the screen before 
creating a chart. You select each data series in Point mode. 
You can select individual items and multiple ranges for each 
data series. LightShip charts exactly what you select, so be 
careful about selecting blank cells, which LightShip treats as 
zeros. YOu can only select one data series at a time. You must 
exit and return to Point mode for each data series that you 
chart. 


The default chart is a bar chart. To change a chart type, see 
“Changing the Chart Type of a Data Series." 


© To create a chart: 
1. Choose Tool Chart. 
2. Drag or click the mouse to create the object. 


3. Choose Chart Data New Series, double-click on the object, 
Or press F2. 


The screen changes to Point mode. 


4. Drag the mouse over the first data series you want to chart 
so that it is highlighted. 
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Figure 6-7 Changing the Chart Type 


3. Choose the data series by selecting one of the numbered 
buttons. 


4. Select one of the chart type icons. 
5. If desired, select another data series and chart type icon. 


6. Choose OK when you are finished. 


Bar Charts 


A bar chart draws bars between the crosses line and the data 
points. Bar charts are the default chart type, so you do not 
need to select the Bar button unless you are changing from 
another type of chart. If more than one data series is a bar 
type, the bars appear next to each other at each tickmark, 
rather than in front of each other. These bars are in the same 
cluster. 
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Adding a Data Series 


@ To add another data series: 


1. Choose Chart Data New Series, press F2, or double-click 


on the object. 


The screen changes to Point mode. 


PightShip: Point to 2ud Chant Data 
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Select the next data series. 


Choose OK! on the menu bar. 


The second data series is graphed on the same chart as the 


first data series. 
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Creating New 
Clusters 


When more than one data series is a bar type, the bars are in 
the same cluster by default. This means they are drawn next to 
each other at each data point. When you create a new cluster, 
the bars for that data series are drawn in front of the previous 
data series. The data in the front must be smaller than the 
data in the back or the data in back is hidden. You can ensure 
that all bars are visible by making each data series narrower 
than subsequent data series (see Figure 6-10). 


@ To create a new cluster: 


Turn on the New Cluster button for a data series. 
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@ To delete a data series: 
Choose Clear All! on the menu bar. 


2. Choose OK! on the menu bar when you are finished. 


Changing the Chart Type of a Data Series 


Each data series you chart has a chart type, for example, bar, 
line, area, or pie. You use the Chart Type dialog box to change 
the chart type and the attributes associated with that type. You 
choose a data series by selecting the number of the series. For 
example, the 1st button selects the first data series you 
charted; the 2nd button selects the second data series you 
charted, and so on. The settings for that data series then 
display in the dialog box and you can change them. You can 
change as many data series as you want before choosing OK. 


To read about each of the chart types in detail, see the 
following sections. 


@ To change a chart type: 
1. Select the chart. 
2. Choose Chart Type. 


A dialog box appears. 
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Line Charts 


A line chart draws a line connecting the data points. 


Figure 6-12 A Line Chart 


Changing @ To change the flatness of a line: 
Flatness 
Type in a number from zero to 100 in the % Flat box. 


In Figure 6-13, the chart on the left has a % Flat setting of zero 
and the chart on the right has a % Flat setting of 100. 


Figure 6-13 How % Flat Affects Line Charts 
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You can specify the width and overlap between bars, create 
new clusters so that the bars appear in front of each other, or 
stack them on top of each other to show totals. 


Figure 6-8 Same-Clustered Bars 


Changing Width You can change the width and overlap of bars. When bars are 
and Overlap in the same cluster, the width you specify for the first data 
series sets the width for all other data series that you display as 
bars. Only bars in the same cluster can overlap. 
@ To change the width of bars: 


Type a number from one to 100 in the % Width box. 


@ To specify the amount of overlap between bars: 
Type a number from zero to 100 in the % Overlap box. 
This number represents the percentage that each 
subsequent data series in the same cluster will overlap. 


Figure 6-9 shows a bar chart with a % Overlap setting of 
25. 


6-11 


LightShip User's Guide 


Changing Width 


Figure 6-15 How % Flat Affects Area Charts 


If you enter a width setting for an area chart, it affects the first 
and last data point. A wide width makes the first and last data 
point protrude as far as possible. A narrow width makes the 
first and last data points start and drop off at a sharp angle. In 
Figure 6-16, the chart on the left has a width of 100, while the 
chart on the right has a width of zero. 


Figure 6-16 How % Width Affects Area Charts 


@ To change the width of areas: 


Type a number from zero to 100 in the % Width text box. 


Pie Charts 


The data in a pie chart is represented as wedges within a circle. 
A LightShip pie chart displays data counterclockwise, with the 
first wedge starting at 3 o’clock. You can change the width of 
the circle, change the degree at which the first wedge begins, 
and change the direction in which the data displays. 
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as shown in Figure 6-11. The 


second and third data series in this chart have Stacked and 


New Cluster on. 


’ 


You can stack a bar chart 


Stacking Bars 


d Bar Chart 


Figure 6-11 A Stacke 
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Changing @ To change the direction of data from counter- 
Direction clockwise to clockwise: 


Turn on the Clockwise check box. 
Coloring Pie @ To color the wedges in a pie: 
Wedges 
1. Choose Chart Color. 


2. Select a data series number. 


The first wedge of the pie is 1st Chart Data, the second 
wedge of the pie is 2nd Chart Data, and so on. 


4. Selecta color. 


4. You can continue selecting data series numbers and colors 
until you are finished. 


5. When you are finished, choose OK. 


Horizontal Charts 

Charts are vertical by default. 

@ To make an area, bar, or line chart horizontal: 
1. Select the chart. 


2. Turn on the Horizontal check box in the Chart Type 
dialog box. 
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Changing Width @ To change the width of a line: 


Type in a number from zero to 100 in the % Width box. 


Stacking Lines You can stack line charts, as shown in Figure 6-14. 


Figure 6-14 A Stacked Line Chart 


Area Charts 


An area chart fills in the area between the crosses line and the 
data point. Area charts are best for charting the first data 
series in a chart or for charting a single data series. 


Changing @ To change the flatness of an area: 
Flatness 
Type in a number from zero to 100 in the % Flat box. 


Figure 6-15 shows a chart on the left with a % Flat setting of 
zero and a chart on the right with a % Flat setting of 100. 
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Figure 6-19 Selecting Legends 


3. Select the legends in the order that you want them to 
appear. 


4. Choose OK! on the menu bar. 
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Figure 6-20 Displaying Legends 
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Pie charts only graph one data series at a time. If you select 
multiple data series and define them as pie charts, pie charts 
display on top of each other. The data series’ are charted in 
order, so that the first pie will be furthest back, the second pie 
will be next, and so on. You can make them all visible by 
changing the width of the ones in front so that they are 
smaller. 


Figure 6-17 A Pie Chart 


Changing Pie 
Width @ To change the width of a pie chart: 


Type a number from one to 100 in the % Width box. 
@ To specify the degree at which the first wedge begins: 
Type a number from zero to 359 in the Angle box. 


For example, to start charting at 12 o’clock, type 90. 
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Types of Menu 
Objects 


Chapter 7 
Creating Menu Objects 


This chapter explains how to create menu-bar menus and 
special hidden menu objects used only for executing actions. 


What is a Menu Object? 


A menu object allows you to perform actions. Menu objects 
perform the same actions as hotspots; for example, they can 
execute commands, call functions, and set parameters. 


Menu objects are not normally displayed on the screen. To 
see them at the Author level, turn on View Show Hidden 
Objects. 


There are three types of menu objects: 


Menu-Bar Menu-bar menu objects display menus on the 
menu bar at the Browse and Capture levels. 
Actions are executed when you choose the 
menu item or the menu-bar name or when an 
Execute Menu action is performed by another 
menu object or hotspot. 


Event-Driven Event-driven menu objects are special objects 
provided by LightShip that do not appear on 
the menu bar. Actions are executed when a 
specific event occurs, such as a file opening or 
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The Menu Object 
Menu 


closing, or when an Execute Menu action is 
performed by another menu object or hotspot. 


Execute Execute menu objects are user-defined menu 
objects that do not display on the menu bar. 
The purpose of these objects is to remain 
hidden and execute actions when called by 
another hotspot or menu object’s Execute 
Menu action. 


When you create or select a menu object, the Menu object 
menu appears. This menu allows you to: 


= Assign a name and item. 

= Define actions. 

= Assign parameter values and pass parameters to other 
files. 


Creating Menu Objects 

To create any type of menu object, you define: 
1. Amenu-bar name 

2. (Optional) A menu-item name 


3. (Optional) The actions associated with the menu name or 
item. For example, actions allow you to: 


= Execute Windows, DOS, DDE and LightShip 
commands. 

= Perform mathematical operations and functions. 

= Perform branching logic. 

= Manipulate strings. 


For more information on how to define actions and the 
order in which they are executed, see Chapter 9: Defining 
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Actions. For information about a specific action, see the 
LightShip Reference Guide. 


4. (Optional) Parameters. You can assign values to 
parameters and pass them to other screens when menu 
object actions are executed. For more information about 
how to define parameters, see Chapter 10: Using 
Variables and Parameters. 


Creating Menu-Bar Menu Objects 


Menu-bar menu objects display on the menu bar at the Browse 
and Capture levels. Actions are executed when you choose the 
menu item or the menu-bar name or when the menu object is 
called by a Execute Menu action performed by another menu 
object or hotspot. 


Figure 7-1 shows the menu objects that make an example 
Chart menu. You create a new menu object for each menu 
item. Each item on a menu has the same menu-bar name. 


LightShip - E\EXAMPLE S\CHAP7\CHMENU.LSF 
File Edit Options View Special Tool 


Menu Bar: &Chart 
Menu Item: &£Bar 


Menu Bar: &Chart ` 
Menu Item: Area ` 


Menu Bar: &Chart 
Menu Item: £Pie 


Menu Bar: &Chart 
Menu Item: &Line | 


Figure 7-1 Menu Objects 
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Menu Display 


Menu-bar Names 


Menu Items 


Menu-Bar Names 


At the Browse level, the Chart menu appears as shown in 
Figure 7-2. The LightShip Browse menus (File, Edit, and 
Special) appear to the left of any menu-bar menus, unless you 
turn on Options Hide Menu Bar. 


= LightShip 
Eile Edit Special alee 


Bar 


Figure 7-2 A Menu at the Browse Level 


Any letter of a menu-bar name preceded by an ampersand (&) 
can be used as a shortcut key; the letter appears underlined on 
the menu-bar name. For example, if you type &Chart, the 
menu-bar name will read Chart. You can press ALT and the 
underlined character to display the menu. 


You can have just a menu-bar name with no item, and still 
have actions and parameters associated with it. The usual 
convention is to follow a menu-bar name with no items 
attached to it with an exclamation point (!). For example, a 
Return! menu is a standard way of returning to a higher-level 
screen. 


Menu-item Names 


Creating a Menu- 
Bar Menu Object 
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A menu item is optional. If a menu item leads to a screen that 
prompts for more information before an action is executed, it 
is conventional to follow it with ellipses (...). 


For menu-item names, any letter that you precede with an 
ampersand (&) can be used as a shortcut key; the letter 
appears underlined on the menu-item name. For example, if 
you type &Bar, the menu item will read Bar. You can press the 
underlined character to carry out the action(s) when the menu 
is displayed. 

© To create a menu-bar menu object: 

1. (Optional) Choose View Show Hidden Objects. 

2. Choose Tool Menu. 


3. Drag or click the mouse to create the menu object. 


4. Choose Menu Names, press F2, or double-click on the 
object. 


A dialog box appears. 


LJiinsert Separator: 
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Figure 7-3 Creating a Menu 
5. Type amenu-bar name in the Menu Bar text box. 


6. (Optional) Type the menu item in the text box labelled 
Menu Item. 
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Inserting a 
Separator 


TS To create an- 


other item on the 
same menu, select 
the menu, press 


INS to make a copy, 


and then double- 
click on the copy to 
change the item 
name. 


8. 


P. 


= To draw a line before a menu item: 
Select Insert Separator. 


For example, on the LightShip File menu, Save As... 
and Print are separated by a line. 


Choose OK. 


Figure 7-4 shows how a menu object looks on the screen. 
You might want to resize the object around the text. 
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Figure 7-4 A Menu Object 
(Optional) Choose Menu Actions to define the actions. 


(Optional) Choose Menu Parameters to define 
parameters. 
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An Example of Creating a Menu-Bar Menu 


This section steps through part of the creation of a menu 
called Chart with menu items on it called Bar, Area, Line, and 
Pie. When you choose an item from the menu, it changes the 
chart type of a chart displayed on the screen. 


1. Choose Tool Menu to create a menu object called &Chart 
with an item called &Bar. 


[iinsert Separator: 
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Figure 7-5 Creating a Menu Object 


2. Make three copies of the menu object and change the 
items to &Area, &Pie, and &Line. 


3. For each menu object, choose Menu Parameters and 
define the parameters. Figure 7-6 shows the parameters 
defined for &Bar. 


Menu Action Parameters 
Name: Yalue: | Cancet } 
E Lemn 


Name = Value List: 


title = Bar Chart 


Figure 7-6 Defining Menu Parameters 
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[25 Important 


Displaying Menus 
on the Menu Bar 


Hiding the 
LightShip Browse 
Menus or the 
Menu Bar 


Ordering Menu-Bar Menus and Menu Items 


The front-to-back order of menu-bar menu objects specifies 
the order that menu names appear on the menu bar and the 
order that menu items appear on the menu. 


Menu-bar names appear on the menu bar and menu items 
appear on the menu in the order in which you create them, 
unless you turn on Special Create in Back. That is, they display 
from back to front and the menu object furthest back is the 
first to appear. Use the Special Send and Bring commands to 
change the order in which they appear by changing their 
positions relative to the other menu objects. 


The order of menu objects may also affect the order in which 


actions are executed. For more information, see Chapter 9: 
Defining Actions. 


Displaying Menu-Bar Menus 


Menu-bar menus do not appear on the menu bar at the Author 
level. 


@ To see a menu after you have created it: 

Choose Special Author or press F4. 
@ To return to the Author level: 

Choose Special Author or press F4. 
User-defined menus appear on the menu bar to the right of 
the LightShip Browse level menus (File, Edit, and Special) at 
the Browse level by default. If you have user-defined menus, 


you can hide the LightShip Browse menus by choosing 
Options Hide Menu Bar. If you have no user-defined menus, 


Creating an 
Execute Menu 
Object 
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and you turn on Options Hide Menu Bar, the menu bar is not 
displayed. 


@ To hide the LightShip Browse menus or the menu 
bar: 


At the Author level, choose Options Hide Menu Bar. 


Creating Execute Menu Objects 

Execute menu objects are user-defined menu objects that do 
not display on the menu bar. Their purpose is to remain 
hidden and execute actions when called by another hotspot or 
menu object’s Execute Menu action. 

Execute menu objects are identified by two ampersands 
preceding their menu-bar names. They do not require an item 
name, but you can type a comment in the Menu Item text box, 
if desired. 

@ To create an execute menu object: 

1. (Optional) Turn on View Show Hidden Objects. 

2. Choose Tool Menu. 


3. Drag or click the mouse to create the menu object. 


4. Choose Menu Names, press F2, or double-click on the 
object. 


The Menu Names dialog box appears. 


5. Type amenu-bar name that begins with two ampersands 
(&&). 


6. (Optional) Type a comment in the text box labelled Menu 
Item. 
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7. (Optional) Choose Menu Actions to define one or more 
actions. 


8. (Optional) Choose Menu Parameters to define one or 
more parameters. 


Executing an The only way to call an execute menu is with the Execute 

Execute Menu Menu action. For more information, see "Executing a Menu" in 
Chapter 9: Defining Actions or see the Execute Menu action in 
the LightShip Reference Guide. 


Creating Event-Driven Menu Objects 


LightShip provides four special event-driven menu objects. 
These menu objects are used solely for performing actions; 
they do not appear on the menu bar as menus. Their actions 
are executed when a specific event occurs or when they are 
called by a Execute Menu action performed by another menu 
object or hotspot. They execute actions at all levels. 


The menu object name is preceded by two ampersands and it 
reflects the event that triggers the action. They do not require 
an item name, but you can type a comment in the Menu Item 
text box, if desired. 


The menu objects and the events that trigger their actions are 
shown in Table 7-1. 
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Table 7-1 Event-Driven Menu Objects 


&&Recalc 


A screen opening. 

Updating parameters. 
Issuing a request for external 
data. 

Issuing a Calculate Now 
command. 


@ To create an event-driven menu object: 


1. (Optional) Turn on View Show Hidden Objects. 
2. Choose Tool Menu. 
3. Drag or click the mouse to create the menu object. 


4. Choose Menu Names, press F2, or double-click on the 
object. 


The Menu Names dialog box appears. 


5. Type amenu-bar name in the Menu Bar text box that 
begins with two ampersands, for example, &&Open. 


6. (Optional) Type a comment in the text box labelled Menu 
Item. 


7. (Optional) Choose Menu Actions to define one or more 
actions. 


8. (Optional) Choose Menu Parameters to define one or 
more parameters. 


LightShip User’s Guide 


&&Open 


[2S Important 


&&Close 
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Use &&Open to perform actions when a screen opens, such as 
initializing variables or starting another application. 


An &&Open object’s actions are executed before all other 
actions, but it is still affected by the order of objects on the 
screen. For example, if you define a parameter with &&Open 
using the Point option, you must make sure that the document 
loads its data before the parameter value is assigned. 
Otherwise, the parameter is assigned a null value because it 
points to a value that has not been displayed yet. You can 
avoid this by making sure the document object is in front of 
the &&Open object. If it’s appropriate, you might want to 
select the menu object and choose Special Send to Back to 
ensure that the document object is loaded before the &&Open 
object executes. 


Ifan &&Open object performs an Execute Menu action, the 
menu being executed must be in front of the &&Open object. 


Use &&Close to perform actions when a screen closes, such as 
closing applications and deleting global variables. Figure 7-7 
shows a DDE Execute action associated with an &&Close 
menu object. This action closes Excel when the screen closes. 


DDE Execute Action 
Application: 


item: | [close{faize)) [quit()] 


EJ Auto Start Program 
Command Line: 
Startup Directory 


Figure 7-7 Performing a DDE Execute Action When a Screen Closes 


&&Recalc 


&&Error 
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Use &&Recalc to execute actions whenever a screen opens, a 
Calculate Now is issued, parameters are updated, or when 
requests for external data are executed. One way to use 
&&Recalc is to assign parameter values or perform calculations 
by pointing to text in a document object on the screen. 


Note that it is especially important to pay attention to the 
order in which actions are performed when you are assigning 
parameter values by pointing with &&Recalc. For example, 
suppose you have a document object that displays actual and 
budget figures and you use a &&Recalc object to point to the 
figures and subtract them to produce variance figures. The 
variance figures are displayed in a user-entry document. In 
this case, the document object that the &&Recalc object is 
pointing to must be in front of the &&Recalc object so that the 
data is loaded before the &&Recalc object points to it. The 
&&Recalc object, which performs the calculation and produces 
the result variable, must be in front of the user-entry 
document that displays the result variable. 


Use &&Error to execute actions when any LightShip system 
error occurs. For example, if you attempt to open a file that 
LightShip cannot find for some reason, you can use this to 
return to a higher level screen. 


Displaying Menu Objects on the Screen 


Menu objects do not display at the Author level when they are 
not selected. 


@ To display menu objects: 
Choose View Show Hidden Objects. 
The menu object appears with its name and item. 


Or 
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Choose View Outline All Objects. 


All the objects on the screen are outlined with a dotted 
line. 


Changing a Menu Name or Item 
@ To change a menu name or item: 
1. Select the menu object. 


2. Choose Menu Names, press F2, or double-click on the 
object. 


The Menu Names dialog box appears. 
3. Type anew menu name in the Menu Bar text box or click 
on the insertion point to edit the existing menu name in 


the Menu Bar text box. 


4. Type an item name or click on the insertion point to edit 
the existing item name in the Menu Item text box. 


5. Choose OK. 
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Chapter 8 
Creating Hotspots 


Hotspots are a key element of any LightShip application. This 
chapter describes how to create and use hotspots. 


What is a Hotspot? 


A hotspot is an area of the screen that performs action(s) when 
you click on it. Hotspots can perform the same actions as 
menu objects; for example, they can execute commands, call 
functions, and set parameters. 
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Figure 8-1 Hotspots 
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Highlight and 
Button Style 
Hotspots 


The Hotspot 
Menu 


At the Browse level, you can tell when you are pointing to a 
hotspot because the cursor changes to a hand. For informa- 
tion on how to change the cursor to another symbol, see 
“Changing the Cursor." 


Hotspots are not displayed by default so that you can place 
them on other objects. Figure 8-1 shows a screen with a non- 
displayed hotspot placed over each image object. Another use 
of a non-displayed hotspot is to place it over a document 
object where you can use functions to return the value, row, 
or column that you click on. 


You can control highlighting and create hotspots that look like 
command buttons, check boxes, or option buttons. For more 
information, see "Creating Hotspot Buttons." 


When you create or select a hotspot, the Hotspot menu 
appears on the menu bar. Use this menu to: 


= Define actions. 

= # Assign parameter values and pass parameters to other 
files. 

= Specify a hotspot cursor file. 

= Specify whether or not text is required to make the 
hotspot active. 

= Specify how the hotspot displays, for example, the style 


and highlighting. 


Creating a Hotspot 


A hotspot can be small, for example, a single cell or button, or 
it can be large enough to cover multiple rows and columns in 
a document object. For more information about placing a 
hotspot over a document object, see "Placing a Hotspot in 
Front of a Document Object." 


Creating a 
Hotspot 
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@ To create a hotspot: 


im 


(Optional) Choose View Outline Hotspots. 


Hotspots are not displayed unless you specify otherwise 
by turning on Hotspot Button Style. 


Choose Tool Hotspot. 


Place the mouse on the upper-left corner of the area that 
you want to define as a hotspot and drag the mouse down 
and to the right. 


(Optional) Use Hotspot Actions to define the actions that 
the hotspot will execute. For example, actions allow you 
to: 


= Execute Windows, DOS, DDE and LightShip 
commands. 

= Perform mathematical operations and functions. 

= Perform branching logic. 

= Manipulate strings. 


For more information on defining actions, see Chapter 9: 
Defining Actions. For information about a specific action, 
see Chapter 10 of the LightShip Reference Guide. 


(Optional) Use Hotspot Parameters to define parameters. 
You can assign values to parameters and pass them to 
other screens when hotspot action(s) are performed. For 
more information about defining parameters, see Chapter 
10: Using Variables and Parameters. 


(Optional) Use Hotspot Text Required to make the 
hotspot conditional on some specified text. For more in- 
formation, see the section "Making a Hotspot Conditional 
on Text." 
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7. (Optional) Use Hotspot Highlight to determine the on/off 
style of the hotspot and whether it highlights. For more 
information, see "Creating Hotspot Buttons." 


8. (Optional) Use Hotspot Button Style to represent a 
hotspot as a button. For more information, see "Creating 
Hotspot Buttons." 


Creating Hotspot Buttons 


There are two types of hotspots, non-displayed hotspots that 
highlight and button-style hotspots that look like Windows- 
style buttons. Hotspots are not displayed by default. If you 
want to draw your own button or place a hotspot over a 
number, text, or image, use a non-displayed hotspot. A 
button-style hotspot can look like a push button, a check box, 
or an option button. 


Creating Button-Style Hotspots 


Creating Push Push buttons are like Windows-style command buttons. Push 

Buttons buttons can execute any number of times while a screen is 
open. You cannot turn on Hotspot Highlight Oneshot for 
push buttons. 


@ To create a push button: 


1. Select the hotspot. 
2. Choose Hotspot Button Style. 


3. Choose Hotspot Highlight Off. 
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Creating Check 
Boxes 


Creating Option 
Buttons 
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You can create a hotspot that looks like a check box and turns 
either on or off when you click on it. 


@ To create a check box: 
1. Select the hotspot. 
2. Choose Hotspot Button Style. 


3. Choose Hotspot Highlight Toggle. 


Option buttons (sometimes called radio buttons) are groups 
of round buttons, of which only one can be on at a time. 
When one button in the group turns on, the one that was on 
turns off. You are allowed up to three groups. 


OLET] 
OL z] 
OL ens] 


@ To create a group of option buttons: 


1. Select a hotspot. 
2. Choose Hotspot Button Style. 
3. Choose one of the Hotspot Highlight Group options. 


4. Choose the same group item for each hotspot in the 
group. 
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Creating Oneshot 
Hotspots 


Creating Toggle 
Hotspots 


Creating Highlight Hotspots 


When you create non-displayed hotspots, you can control their 
on/off style and their highlighting. If a non-displayed hotspot 
with highlighting enabled has an object behind it, the object’s 
colors invert when you click on the hotspot. 


You can click on oneshot hotspots only once each time the 
screen is opened. When you click on it, the hotspot is 
highlighted as shown on the right of Figure 8-2. It stays 
highlighted until you close the screen or go to another screen. 


@ Tocreate a non-displayed hotspot that can only be 
executed once: 


1. Select the hotspot. 


2. Choose Hotspot Highlight Oneshot. 


Figure 8-2 A Oneshot Hotspot 

You can create a button that behaves like a check box, only it is 
non-displayed. These are called toggle hotspots. A toggle 
hotspot turns on and off each time you click on it. When it is 
on, it is highlighted; when it is off, highlighting turns off. 

@ To create a toggle hotspot: 

1. Select the hotspot. 


2. Choose Hotspot Highlight Toggle. 


Creating a Group 
of Hotspots 


Showing Non- 
Displayed 
Hotspots 
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You can create a group of buttons that behave like option 
buttons but that are non-displayed. These are called hotspot 
groups. Only one hotspot in the group can highlight at a time. 
When one hotspot in the group turns on, the one that was on 
turns off. You are allowed up to three groups. 


@ To create a group: 
1. Select the hotspot. 
2. Choose one of the Hotspot Highlight Group options. 
3. Choose the same group item for each hotspot in the 
group. 
@ To outline hotspots at the Author level: 
Choose View Outline Hotspots. 
or 


Choose View Outline All Objects. 


Making a Hotspot Conditional on Text 


Hotspots are active by default, that is, their actions execute 
when you click on them. You can make a hotspot inactive, 
depending on whether or not there is text on up to three areas 
of the screen. When you point to an inactive hotspot at the 
Browse level, the cursor does not change to the hotspot cursor 
and no actions execute. 


There are several reasons why you might want to make a 
hotspot inactive. For example, you might want to make a 
hotspot inactive if there is no drill-down data available or to 
prevent a blank document object cell from being used as a 
hotspot. 
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Making a Hotspot @ To make a hotspot conditional on text: 
Conditional on 
Text 1. Select the hotspot. 


2. Choose Hotspot Text Required. 
The screen changes to Point mode. 


3. Select the area(s) where text must be present in order for 
the hotspot to be active. 


You can select multiple cells and up to three separate cell 
ranges. 


4. When you are finished, choose OK! on the menu bar. 


Example Figure 8-3 shows an example property management screen 
that allows you to drill-down to more information, if the 
information is available. 


LightShip - F‘\ls\demo\internal\PROPTOP LSI 


4 «= 2SteteSteet f: 


Figure 8-3 Push Button Hotspots with Text Required 
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The hotspot shown selected in Figure 8-3 points to a hidden 
document object that lists the files for different properties, as 
shown in Figure 8-4. 


LightShip: Point to Hotspot Text Required 
Clear alll Lindo! Phat ten! QKI onenn 


oR SRR SERRRRR RS 
* 100 Belle 
* 40 Market 


Figure 8-4 Pointing to Radeinad Text 


Because Text Required points to text in the list, the hotspot’s 
actions will execute. The actions display a document object 
with information about the property. The actions also point to 
text in the hidden document object shown in Figure 8-4, 
which is used for a filename and caption. 


Dimming an Inactive Hotspot 


When Text Required is on, you have the option of making a 
hotspot unavailable by turning on Hotspot Dim If Inactive. 
When the text that is required does not exist and Dim If 
Inactive is on, button-style hotspots disappear. For non- 
displayed hotspots, any object underneath the hotspots dims. 
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Example 


Hotspots 


User-Entry Document 


Object @ (pick) 


Hotspot 


@ To dim a hotspot: 


Choose Dim If Inactive. 


This is an example of dimming an inactive hotspot. 


In this example, each of the numbers in the list has a hotspot 
over it. No actions are defined for any of the hotspots. When 
you click on a number in the list, the number is assigned to a 
parameter called pick. The number you click on displays in a 
user-entry document that contains a reference to @(pick). 


The pencil image also has a hotspot over it with no actions 
defined. Text Required is on and points to the user-entry 
document object that displays the value of @(pick). Dim if 
Inactive is also on for this hotspot. When the pencil is active 
and you click on it, it sets pick to a null value, which makes the 
document object blank. The required text is not there, so the 
text on the pencil dims. 
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Placing a Hotspot in Front of a Document Object 


You can place a hotspot in front of a document object and use 
functions to return information from the cells that you click 
on. You can return the cell value with MOUSETEXT, you can 
return the row with MOUSEROW, and you can return the 
column with MOUSECOLUMN. To use these functions: 


= The hotspot must be in front of the document object. 

= The hotspot must the same size or slightly smaller than 
the document object. 

= The document object must be defined as having columns. 


For more information on other functions to use to return cell 
values, see "Returning Document Cell Values," in Chapter 9: 
Defining Actions. 


When you place a hotspot in front of a document object, you 
might want to use Hotspot Text Required to prevent a blank 
cell from being active. You can point to text in the same 
document object or a separate document object. If you point 
to a range of cells that is not the same size as the document 
object behind the hotspot, LightShip uses the same rules as 
when two function arguments are different sizes. For more 
information, see "Using Cell Ranges as Arguments," in Chapter 
9: Defining Actions. 


Changing the Cursor 


When you point to a hotspot at the Browse level, the cursor 
changes to a hand by default. You can change the cursor by 
using your own cursor file or you can use the pointer, if 
desired. The cursor file must conform to the Windows 3.0 
Cursor Resource File format, which has a .CUR extension. 
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When you specify a cursor file for a hotspot, it is only active for 
that one hotspot. You can specify a default cursor file for all 
hotspots on the Preferences dialog box. For more information 
about the View Preferences command, see the LightShip 


Reference Guide. 
To Specify a @ To specify another cursor file: 
Cursor File 
1. Select the hotspot. 
2. Choose Hotspot Cursor File. 
A dialog box appears. 
Hotspot Cursor File 
Filename: 
Directory: p:\xfer\cur 
Directories: 
C] Search Path 
Figure 8-5 Selecting a Hotspot Cursor File 
3. Enter the cursor filename. 
4. Choose OK. 
Specifying the @ To use the pointer cursor: 


Pointer Cursor 
1. Select the hotspot. 


2. Choose Hotspot Cursor None. 
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Resetting the 
Default Cursor 
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The LightShip default cursor for hotspots is the hand icon. 
Unless you have specified a different cursor file on the 
Preferences dialog box, resetting the default cursor file makes 
the hand icon the hotspot cursor. 

© To reset the default cursor: 

1. Select the hotspot. 


2. Choose Hotspot Cursor Default. 
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Defining Actions 


This chapter discusses how hotspot and menu actions work. 
For information on specific actions or functions, see the 


LightShip Reference Guide. 


What is an Action? 


Actions are operations that hotspots or menu objects execute 


at the Browse level. You can define actions to: 


Activate Windows programs or execute DOS commands. 


Control calculations. 

Enter comments. 

Copy to the Clipboard. 

Perform DDE Requests and Executes. 
Display the retrace path. 

Execute a menu object. 

Write to a file. 

Perform numeric and string functions. 
Perform logical and relational operations. 
Assign and pass parameter values. 
Open files and define the retrace path. 
Print the screen. 

Return to a previous screen. 


Save a file as a permanent or temporary file. 


Execute scroll commands. 

Exit from LightShip. 

Pause for a specified number of seconds. 
Repaint the screen. 
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Editing an Action 


Replacing an 
Action 


This adds the action above the line selected in the Actions 
box. Depending on the action you select, another dialog 
box might appear. For example, if you choose Open File - 
Add to Retrace Path, the Open File Action dialog box 


appears. 


5. You can keep adding actions by selecting them from the 
list and choosing Insert. 

6. When you are finished, choose OK. 

Changing Actions 


To change an action in the Actions box, you must first select it. 
You can select multiple actions by dragging the mouse over 
them or by selecting the first action and then holding down 
SHIFT and selecting the last action. 


To edit an action that was specified on a dialog or 
text box: 


Select the action in the Actions box. 

Choose Replace. 

A dialog or text box for that action appears. 

Make the changes. 

Choose OK. 

To replace an action in the Actions box with a new 
action: 


Select the action you want to replace in the Actions box. 
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Executing a Menu 

Use the Execute Menz action to call any type of menu object. 
The called menu object can execute up to 250 actions and 
returns control to the calling object. 


© To execute a menu: 


1. From the Action dialog box, select Execute Menu and 
choose Insert. 


The Execute Menu Action dialog box appears. 


2. Type the name of the menu object that you want to call in 
the Menu Bar text box. 


3. Ifthe menu object has a menu item, type the name in the 
Menu Item text box. 
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Using Don’t Store 
Result 


For example, the < (Less than) operation shown below asks 
the question "Is a less than b?" If the condition flag is false, the 
actions within the Jf block are executed: 


a<b 
if False Begin 


if End 


For numeric functions, the condition flag is set to true if the 
numbers have non-zero values. For string functions, the 
condition flag is set to true if the strings have any characters. 


All functions set a condition flag; however, you might use the 
following functions most frequently to set a flag: 


= (Equals) 

<> (Not Equal?) 

< (Less than?) 

> (Greater than?) 

> =(Greater or equal?) 


Copy/Test 


Condition flags should be scalar. Otherwise, LightShip uses 
the last cell value in the result variable as the condition flag. 


Condition flags do not require you to store their results, 
although you can if desired. LightShip remembers the result 
until the next action is executed. Use the Don’t Store Result 
option on the Function Action dialog box when you perform a 
conditional test and there is no other use for the result. 
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Reordering Action @ To reorder the objects: 
Objects 
1. First select the object by pressing CTRL+UP ARROW or 
CTRL+DOWN ARROW. 


2. Then use the Special Send and Bring commands to 
control where the objects are in relation to each other. 


Defining Actions 
@ To define actions: 
1. Select the hotspot or menu object. 


2. Choose Actions from the object menu. 


A dialog box appears. 


Select Actions to Edit 
Here 


Select New Actions 
Here 


Figure 9-1 The Actions List Box Displays the Actions for the Object 
3. Select the action in the Action Description box. 


4. Choose the Insert button. 
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Defining Loops 


You can define loops so that actions are carried out 
repeatedly. Loops must begin with a Loop Begin action and 
end with an Loop End action. For example: 


Loop Begin 
action 


action 


Loop End 


Termination There are three ways to control an exit from a loop: 
Conditions 

a Loop Exit 

a Loop Exit If True 

a Loop Continue 


You must always use a Loop Exit or Loop Exit If True action 
before a Loop End action to exit from a loop. Loop Continue 
does not cause an exit, but it allows you to control the exit 
condition. 


Loop Exit Loop Exit allows you to exit from a loop when a condition flag 
is true or false, and to perform some action(s) before exiting. 
You must insert a conditional action, such as an Jf True Begin 
or If False Begin action, before Loop Exit. Then enter the 
action(s) you want to perform. You must insert the Loop Exit 
before the Jf End action. 
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Deleting Actions 


Copying and 
Moving Actions 


Condition Flags 
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Select the new action in the Action Description box. 


Choose Replace. 


To delete action(s): 
Select the action(s) in the Actions box. 


Choose Cut. 


You can copy actions within the same action list and to 
another object’s action list. 


1. 


To copy or move action(s): 

Select the action(s) in the Actions box. 

Choose Cut. 

Select the object you want to paste the action to, if it’s not 
the current object, and choose Actions from that object’s 


menu. 


Select the action below the step where you want to paste 
the action. 


Choose Paste. 


Conditional Actions 


You can perform action(s) based on a condition flag. A 
condition flag is the true or false result of a function. All 
LightShip functions produce a condition flag. 
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Loop Continue 


Loop Continue sends control back to the Loop Begin action. 
You must insert a conditional action, such as an If True Begin 
or an If False Begin, before a Loop Continue action and end 
the block with an Jf End. When the inverse of the Loop 
Continue condition is true, LightShip executes the actions that 
follow the Jf End action until LightShip encounters a Loop 
Exit. 


You can use Loop Continue to evaluate a condition flag before 
looping, or you can use it to branch to another part of the 
loop when some condition is met. For example, the following 
actions set x1, x2, and x3 to 1, 2, and 3 and return x to 1: 


x:=1 
Loop Begin 
x@(x) := x 
X:=xX+T 
x<=3 
if True Begin 
Loop Continue 
if End 
x:=1 
Loop Exit 
Loop End 


What is a Function? 


The Function Action dialog box lists all functions available for 
strings and numbers. A function takes a value or values, 
performs an operation on them, and returns a value. The 
values that you give to a function are called arguments. 
Arguments can be single-cell or multi-cell containers. The 
value that the function returns is called the result variable, 
which can also be a single-cell or multi-cell container. 


LightShip provides both numeric and string functions. The 
difference between them is how the inputs are interpreted by 
LightShip. 


Conditional 
Actions 
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The following conditional actions must follow a condition 
flag: 


a If True Begin 
a If False Begin 
= Loop Exit If True 


You must end an If True Begin and an If False Begin block with 
an If End action. If you use Jf True Begin and the test is false, 
or if you use If False Begin and the test is true, LightShip 
executes the next action after Jf End, unless there is an If Else 
action within the block. 


You can branch to other action(s) by inserting an Jf Else 

action, if desired. For instance, the first action in the following 
example asks the question "Is count >= level?" and sets the 
condition flag to true or false. If the flag is true, the actions 
following the Jf True Begin action execute, and if the flag is 
false, the actions following the Jf Else action execute. 


count> =level 
If True Begin 


action 


if Else 
action 


if End 


9-7 


LightShip User's Guide 


9-12 


Expressions 


Variables 


Literals 


The Copy/Test function, on the other hand, assigns a value to a 
variable: 


counter := 1 


This expression sets counter to the value one. 


An expression is a combination of operators and operands, for 
example, functions, strings, and variables. The values that you 
give to a function are called arguments to the function. 


You can use three types of function arguments: 


= # Variables 
= Literals 
= Point to a document cell value 


A variable can be any variable name you type or select from the 
list in the Function Action dialog box. You can also type a 
variable reference, which will be evaluated before the function 
is performed. 


A literal can be any number or string that you type in the 
Argument text box. 


LightShip assumes that any string on the right side of an 
assignment operator in the Function Action dialog box is a 
variable, if it is not in quotes and follows the rules for a legal 
variable name. If it is not a variable defined in LightShip, 
LightShip substitutes a null value. For example, in the 
assignment statement below, LightShip assumes that temp isa 
variable because it begins with a character, has no spaces in it, 
and is less than 20 characters. 


tempkey :=temp 


Loop Exit If True 
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For example, the following actions set x1, x2, and x3 to 1, 2, 
and 3 and return x to 1: 


x:=1 
Loop Begin 
Xx@(x) := x 
X:=xX+1 
x>3 
if True Begin 
xX:=1 
Loop Exit 
if End 
Loop End 


Loop Exit If True combines an If True Begin action with a Loop 
Exit action. Use Loop Exit If True when you want to test for a 
true condition and then exit immediately. 


You must insert a condition flag before a Loop Exit If True. If 
the condition flag is true, LightShip exits from the loop. For 
example, the following actions set x1, x2, and x3 to 1, 2, and 3 
and return x to 1: 


x:= 1 
Loop Begin 
x@(x) := X 
x:=x+1 
x>3 
Loop Exit If True 
Loop End 
x:=1 
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Relationship 
Between Cell 
Ranges 


I Important 


One-to-One 


One-to-Many 
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Two arguments can have the following relationships to each 
other: 


= One-to-one, where the arguments have equal data 


= One-to-many, where one argument is a scalar for the other 
argument 


= $Many-to-many, where the arguments have unequal data 


If you select a blank cell when pointing to a function 
argument, LightShip treats this as a zero for numeric functions 
and as a blank (null value) for string functions. 


A one-to-one relationship occurs when both arguments have 
the same number of rows and columns. LightShip matches the 
cell in Row 1 Column 1 (R1C1) of the first argument to the cell 
in R1C1 of the second argument, and so on. The result is 
returned into R1C1 of the result variable. 


The following example shows concatenation where both 
arguments have an equal number of rows and columns. 


In a manner similar to a one-to-one relationship, if one 
argument is a single number and the other argument points to 
multiple numbers, the single number acts as a scalar for each 
of the other argument’s values. The result container is the 
same size as the larger argument. 


The following example shows concatenation where the first 
argument is a single cell that is concatenated to all cells in the 
second argument. 


The Result 
Variable 


Assignment 
Operator 
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For operations that return Boolean results and for condition 
flags for all functions, strings are checked for characters 
(length) and numerics are checked for a zero or non-zero 
value. Zeros and nulls are interpreted as false and non-zero 
and non-null values are interpreted as true. 


How Function Actions are Displayed 


LightShip displays functions in the Function Action dialog box, 
which opens from the Action dialog box. 


The result variable appears on the left side of an assignment 
statement as shown: 


variable := expression 


This variable contains the results of the function. It must be a 
variable or a reference to a variable, for example, @(item). 
References to variables are always evaluated first, before the 
operation is performed. 


The assignment operator (:=) means “assign the value of" and 
should not to be confused with an equivalence operator (=). 
For example, (=) Equal is a relational operation that returns a 
Boolean value to the result variable: 


result := counter = 1 

This operation asks the question "Does counter=1?" If 
counter=1, result is assigned the value 1. If counter<>1, 
result is assigned the value zero. If you choose not to store 


the result, it appears as: 


counter = 1 
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Returning Document Cell Values 


There are many functions you can use to return information 
about the value in a document object cell. The functions listed 
below are especially useful for finding the value in a cell, or 
the row and column number of a cell on which you click. 

Note that the MOUSE functions require that you place a 
hotspot in front of the document object and then define the 
function for that hotspot. 


= Use MOUSETEXT to return the cell value on which you 
click at the Browse level. 


=» Use MOUSEROW to return the row number of the cell on 
which you click at the Browse level. 

= Use MOUSECOLUMN to return the column number of the 
cell on which you click at the Browse level. 

= Use Copy/Test to return cell value(s) whose position(s) 
you have selected using the Point option. 

= Use FETCH to return the value of a cell that you specify by 
row and column numbers. 

= Use STORE to return a value into a cell that you specify by 


row and column number. 


Point 


Selecting Data in 
Columns 
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To guarantee that LightShip correctly interprets strings and 
variables on the right side of an assignment operator (in the 
Function Action dialog box), we recommend enclosing strings 
in double quotes (""), for example: 


tempkey:=""temp" 


To include double quotes in a string, you must type two of 
them. For example: 


tempkey :=""""temp"" 
evaluates to: 


v8 temp" 


You can point to one or more cell values in a document object. 
For more information about pointing to document object 
data, see "Using Cell Ranges as Arguments." 


Using Cell Ranges as Arguments 


You can use single-cell or multi-cell containers or document 
objects as function arguments. This section discusses how 
rows and columns behave when you use them as arguments. 


To select data from multiple columns, the document object 
must have Document Layout Columns turned on and a 
column delimiter defined. If you select multiple rows and 
columns without a column delimiter defined, LightShip 
interprets each row as one cell and you will get unexpected 
results. For information about defining columns, refer to 
Chapter 4: Displaying Data. 


9-13 


LightShip User’s Guide 


9-18 


You can type in strings or variables in the text box, select 
variables from the drop-down list, or you can point to 
document object cells by choosing the Point button. For 
information about how to assign values by pointing, see 
Chapter 10: Using Variables and Parameters. For 
information about how cell ranges relate to each other 
when used as function arguments, see "Using Cell Ranges 
as Arguments." 

Enclose strings in double quotes. 

@ To enter a null string, type: 


© To select a variable from the list: 


= Click the down arrow next to the Argument(s) text 
box. 


= Select the variable. 

Define the result variable. 

You can type a variable name or a variable reference, or 
select a variable from the list. References to variables are 
always evaluated first, before the operation is performed. 


© To select a variable from the list: 


= Click the down arrow next to the Result Variable text 
box. 


= Choose the variable. 


Choose OK. 


Many-to-Many 
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When one argument has less rows or columns than the other 
argument, the smaller argument’s rows or columns are reused 
to match the additional rows and columns of the larger 
argument. This repeats until the result’s container is the same 
size as the larger argument. 


The following example shows concatenation where the first 
argument has less rows than the second argument. The first 
argument’s row is concatenated to the first and second rows of 
the second argument. 


The same is true for columns. The following example shows 
concatenation where the first argument has more columns 
than the second argument. The last column of the first 
argument is concatenated to the first column of the second 
argument to return a container of the same size as the larger 
argument. 
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When Actions are Executed 


Hotspots A hotspot’s actions are executed when you click on it at the 
Browse level. 


Menu Objects Any menu object’s actions can be executed by an Execute 
Menu action at the Browse level. In addition: 


= Amenu-bar menu object’s actions execute when you 
choose a menu item at the Browse level. 


= An event-driven menu object’s actions execute when the 
event occurs at any level. 


Controlling the Order of Execution 


You can define up to 250 actions for each object in the Action 
dialog box. Actions execute in the order in which they are 
listed, unless the order is changéd by a conditional action. 


Parameters are assigned before the first action is carried out. 
One way to pass parameters that have been changed by actions 
is to use an Execute Menu action to call another menu object 
and assign the parameters there. 


If you place two or more hotspots or menu objects over each 
other, their action(s) execute in the order in which they are 
placed, from front to back. That is, the action of the object 
that is closest to the front is carried out first. 


Any actions that follow an Open File or a Return in Path action 


are not executed. These actions cause control to transfer to 
the called screen. 
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For more information about using hotspots in front of 
document objects, see Chapter 8: Creating Hotspots. For 
more information about a specific function, see Chapter 10 in 
the LightShip Reference Guide. 


Defining a Function 
@ To define a function: 


1. Select Function from the Action Description box in the 
Action dialog box and choose Insert. 


Or 

Choose the Function button. 

A dialog box appears, shown in Figure 9-2. The string 
functions are listed by default. To define a numeric 


function, choose Numeric. The numeric functions appear 
in the Operation list box. 


Function Action 


Result Variable 


peee Argument{s) 


C] Don't Store Result 


Variables List Boxes 


Operation 
‘opy/Test vanable 
enate strings 


CHOOSE (Cell by row/column) 
Lahat ee A within string) 


Point to Data in 


D t Object 
TESEN Eae Oba Oiek 


Figure 9-2 Defining Functions 


2. Select the function in the Operation list box. 
A prompt for the arguments appears. 


3. Define the arguments. 
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Editing an Action 


Replacing an 
Action 


This adds the action above the line selected in the Actions 
box. Depending on the action you select, another dialog 
box might appear. For example, if you choose Open File - 
Add to Retrace Path, the Open File Action dialog box 


appears. 


5. You can keep adding actions by selecting them from the 
list and choosing Insert. 

6. When you are finished, choose OK. 

Changing Actions 


To change an action in the Actions box, you must first select it. 
You can select multiple actions by dragging the mouse over 
them or by selecting the first action and then holding down 
SHIFT and selecting the last action. 


To edit an action that was specified on a dialog or 
text box: 


Select the action in the Actions box. 

Choose Replace. 

A dialog or text box for that action appears. 

Make the changes. 

Choose OK. 

To replace an action in the Actions box with a new 
action: 


Select the action you want to replace in the Actions box. 
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When Actions are Executed 

Hotspots A hotspot’s actions are executed when you click on it at the 
Browse level. 

Menu Objects Any menu object’s actions can be executed by an Execute 


Menu action at the Browse level. In addition: 


= Amenu-bar menu object’s actions execute when you 
choose a menu item at the Browse level. 


= An event-driven menu object’s actions execute when the 
event occurs at any level. 


Controlling the Order of Execution 


You can define up to 250 actions for each object in the Action 
dialog box. Actions execute in the order in which they are 
listed, unless the order is changéd by a conditional action. 


Parameters are assigned before the first action is carried out. 
One way to pass parameters that have been changed by actions 
is to use an Execute Menu action to call another menu object 
and assign the parameters there. 


If you place two or more hotspots or menu objects over each 
other, their action(s) execute in the order in which they are 
placed, from front to back. That is, the action of the object 
that is closest to the front is carried out first. 


Any actions that follow an Open File or a Return in Path action 


are not executed. These actions cause control to transfer to 
the called screen. 
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Using Don’t Store 
Result 


For example, the < (Less than) operation shown below asks 
the question "Is a less than b?" If the condition flag is false, the 
actions within the Jf block are executed: 


a<b 
if False Begin 


if End 


For numeric functions, the condition flag is set to true if the 
numbers have non-zero values. For string functions, the 
condition flag is set to true if the strings have any characters. 


All functions set a condition flag; however, you might use the 
following functions most frequently to set a flag: 


= (Equals) 

<> (Not Equal?) 

< (Less than?) 

> (Greater than?) 

> =(Greater or equal?) 


CONTAINS 
EXISTS 
Copy/Test 


Condition flags should be scalar. Otherwise, LightShip uses 
the last cell value in the result variable as the condition flag. 


Condition flags do not require you to store their results, 
although you can if desired. LightShip remembers the result 
until the next action is executed. Use the Don’t Store Result 
option on the Function Action dialog box when you perform a 
conditional test and there is no other use for the result. 
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You can type in strings or variables in the text box, select 
variables from the drop-down list, or you can point to 
document object cells by choosing the Point button. For 
information about how to assign values by pointing, see 
Chapter 10: Using Variables and Parameters. For 
information about how cell ranges relate to each other 
when used as function arguments, see "Using Cell Ranges 
as Arguments." 
Enclose strings in double quotes. 
@ To enter a null string, type: 

sees 


@ To select a variable from the list: 


m Click the down arrow next to the Argument(s) text 
box. 


= # Select the variable. 

4. Define the result variable. 
You can type a variable name or a variable reference, or 
select a variable from the list. References to variables are 
always evaluated first, before the operation is performed. 


© To select a variable from the list: 


= Click the down arrow next to the Result Variable text 
box. 


= Choose the variable. 


5. Choose OK. 
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Defining Loops 


You can define loops so that actions are carried out 
repeatedly. Loops must begin with a Loop Begin action and 
end with an Loop End action. For example: 


Loop Begin 
action 


action 


Loop End 


Termination There are three ways to control an exit from a loop: 
Conditions 

a Loop Exit 

a Loop Exit If True 

a Loop Continue 


You must always use a Loop Exit or Loop Exit If True action 
before a Loop End action to exit from a loop. Loop Continue 
does not cause an exit, but it allows you to control the exit 
condition. 


Loop Exit Loop Exit allows you to exit from a loop when a condition flag 
is true or false, and to perform some action(s) before exiting. 
You must insert a conditional action, such as an If True Begin 
or If False Begin action, before Loop Exit. Then enter the 
action(s) you want to perform. You must insert the Loop Exit 
before the Jf End action. 
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Returning Document Cell Values 


There are many functions you can use to return information 
about the value in a document object cell. The functions listed 
below are especially useful for finding the value in a cell, or 
the row and column number of a cell on which you click. 

Note that the MOUSE functions require that you place a 
hotspot in front of the document object and then define the 
function for that hotspot. 


= Use MOUSETEXT to return the cell value on which you 
click at the Browse level. 


= Use MOUSEROW to return the row number of the cell on 
which you click at the Browse level. 

= Use MOUSECOLUMN to return the column number of the 
cell on which you click at the Browse level. 

= Use Copy/Test to return cell value(s) whose position(s) 
you have selected using the Point option. 

= Use FETCH to return the value of a cell that you specify by 
row and column numbers. 

= Use STORE to return a value into a cell that you specify by 


row and column number. 
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Loop Continue 


Loop Continue sends control back to the Loop Begin action. 
You must insert a conditional action, such as an If True Begin 
or an If False Begin, before a Loop Continue action and end 
the block with an Jf End. When the inverse of the Loop 
Continue condition is true, LightShip executes the actions that 
follow the Jf End action until LightShip encounters a Loop 
Exit. 


You can use Loop Continue to evaluate a condition flag before 
looping, or you can use it to branch to another part of the 
loop when some condition is met. For example, the following 
actions set x1, x2, and x3 to 1, 2, and 3 and return x to 1: 


x:=1 
Loop Begin 
x@(x) := x 
X:=xX+1 
x<=3 
if True Begin 
Loop Continue 
if End 
x:=1 
Loop Exit 
Loop End 


What is a Function? 


The Function Action dialog box lists all functions available for 
strings and numbers. A function takes a value or values, 
performs an operation on them, and returns a value. The 
values that you give to a function are called arguments. 
Arguments can be single-cell or multi-cell containers. The 
value that the function returns is called the result variable, 
which can also be a single-cell or multi-cell container. 


LightShip provides both numeric and string functions. The 
difference between them is how the inputs are interpreted by 
LightShip. 
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Relationship 
Between Cell 
Ranges 


IF Important 


One-to-One 


One-to-Many 
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Two arguments can have the following relationships to each 
other: 


= One-to-one, where the arguments have equal data 


= One-to-many, where one argument is a scalar for the other 
argument 


= §Many-to-many, where the arguments have unequal data 


If you select a blank cell when pointing to a function 
argument, LightShip treats this as a zero for numeric functions 
and as a blank (null value) for string functions. 


A one-to-one relationship occurs when both arguments have 
the same number of rows and columns. LightShip matches the 
cell in Row 1 Column 1 (R1C1) of the first argument to the cell 
in R1C1 of the second argument, and so on. The result is 
returned into R1C1 of the result variable. 


The following example shows concatenation where both 
arguments have an equal number of rows and columns. 


In a manner similar to a one-to-one relationship, if one 
argument is a single number and the other argument points to 
multiple numbers, the single number acts as a scalar for each 
of the other argument’s values. The result container is the 
same size as the larger argument. 


The following example shows concatenation where the first 
argument is a single cell that is concatenated to all cells in the 
second argument. 
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Expressions 


Variables 


Literals 


The Copy/Test function, on the other hand, assigns a value toa 
variable: 


counter := 1 


This expression sets counter to the value one. 


An expression is a combination of operators and operands, for 
example, functions, strings, and variables. The values that you 
give to a function are called arguments to the function. 


You can use three types of function arguments: 


=  ## Variables 
= Literals 
= Point toa document cell value 


A variable can be any variable name you type or select from the 
list in the Function Action dialog box. You can also type a 
variable reference, which will be evaluated before the function 
is performed. 


A literal can be any number or string that you type in the 
Argument text box. 


LightShip assumes that any string on the right side of an 
assignment operator in the Function Action dialog box is a 
variable, if it is not in quotes and follows the rules for a legal 
variable name. If it is not a variable defined in LightShip, 
LightShip substitutes a null value. For example, in the 
assignment statement below, LightShip assumes that temp is a 
variable because it begins with a character, has no spaces in it, 
and is less than 20 characters. 


tempkey :=temp 


Variables 


Parameters 


Chapter 10 


Using Variables and Parameters 


This chapter explains how to create and use variables and 
parameters. 


Variables and Parameters 


A variable is a container you create by naming it and assigning 
to it a string or numeric value, as shown: 


key = product 


where "key" is the variable name and "product" is the value 
assigned to it. Variables can contain single cells or rows and 
columns. For example, the following variable contains one 
row with four columns: 


keys = product | channel | region | city 


Whenever you use a variable name preceded by an atsign (@) 
and enclosed in parentheses, LightShip substitutes the value of 
the variable. This is called referencing variables, or variable 
substitution. 


Hotspots and menu objects can assign new values to variables 
and pass them to other LightShip screens. When a variable’s 
value changes, we call it a parameter. When we talk about 
"passing parameters," we mean assigning a new value to a 
variable on the current screen or passing a variable to another 
screen. 
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Kinds of Variables 


There are two kinds of variables: 


Local Variables Local variables are only available to the 
screen in which they are created, unless 
they are passed to another screen with 
an Open File action. They are saved 
with the screen. 


Global Variables Global variables are available to all 
screens within one instance of 
LightShip. They are deleted when you 
exit from LightShip unless you 
specifically save them. Global variables 
use an ampersand (&) as the first 
character of their names, for example, 
Gitem. 


Assigning Values 


Variables are updated when an event or action occurs that 
changes their values. The ways you can initialize and update 
variables are listed in "Ways to Assign Values." 


The Calculation commands affect when variables are updated. 
When Calculation Automatic is on, changes in variable values 
are updated immediately. When Calculation Manual is on, 
variables are not updated unless you issue a Calculate Now 
command. 


If you turn Calculation Automatic off, and then turn it on 
again, LightShip updates all parameter values that have been 
changed on the screen since you turned Calculation Automatic 
off or issued the last Calculate Now command. 


The value of a variable at the last assignment remains the 
current value until it is changed. If you close and reopen a file, 
the value of all variables will be the same as when you last 


Order of 
Assignment 


Ways to Assign 
Values 
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saved the file, unless you specifically reinitialize them when 
LightShip starts or when the screen opens. 


The order in which you assign values in a dialog box is not 
important. Assignments occur concurrently. For more 
information, see "Defining and Passing Parameters" and "An 
Example Using Variables and Parameters." 


There are five ways to assign values to variables: 


1. 


The Special Variables command 


This opens the Variables dialog box, which you usually 
use to initialize variables. This dialog box displays the 
current values of all variables, unless you specify 
otherwise. 


The Hotspot or Menu Parameters commands 


These commands open the Hotspot or Menu Action 
Parameters dialog boxes, where you can type in 
assignment(s) that occur when the hotspot or menu is 
executed at the Browse level. For more information, see 
"Defining and Passing Parameters.” 


To reinitialize local and global variables every time you 
open a file, create an &&Open menu object. &&Open is a 
special menu object that sets parameters and carries out 
the action associated with it when the file opens. Use the 
Menu Parameters cormmand to assign parameter values or 
use the Menu Actions command to define a function that 
produces a result variable. For more information about 
&&Open, see "Creating Event-Driven Menu Objects" in 
Chapter 7: Creating Menu Objects. 


The Hotspot Actions or Menu Actions commands 
These commands open the Hotspot or Menu Action dialog 


boxes, where you can define functions that assign values 
to variables. 
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4. In LS.INI 


Assign values to global variables in the [Globals] section 
of LS.INI to reinitialize them every time you start 
LightShip. For example: 


&PATH = C:\LS\;C:\LS\DEMO; 


For more information about LS.INI, see Appendix B: LS.INI 
Options. 


5. The DOS or Windows command line 


Use this option to initialize both local and global 
variables. For example: 


\ls /b \top.lsf &Logan="user" 


For more information, see "Passing Parameters from 
Windows or DOS." 


Limits and Legal Values 


Values You can assign numbers, characters, quoted strings, variable 
names, or variable references, for example, @(actual), to 
variables and parameters. Variable values are limited to 4,000 
characters. 


To include an atsign in a variable value, you must enter it 
twice, for example, @@. 


Strings do not need to be quoted in the Special Variables, 
Hotspot Parameters, or Menu Parameters dialog boxes. 
Strings do need to be quoted in the Function Action dialog 
box. 
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Parameters 


Local and Global 
Variables 


Chapter 10 Using Variables and Parameters 


Variable names are limited to 20 characters. They must begin 
with an alphabetic character, an underscore (_), or an 
ampersand (&). 


You can pass 50 parameters between screens at one time. 
Hotspot and menu objects are allowed 20 parameters per 
object. 


Saving Global Variables 


Global variables are deleted by default when you exit 
LightShip. To save them, turn on the Save Globals option in 
the View Preferences dialog box. When this option is on, any 
global variables you define in the Variables dialog box are 
saved in LS.INI, which reinitializes them every time LightShip 
Starts. 


Creating Variables 


You create variables in the Special Variables dialog box, which 
displays the current values of all global and local variables, 
unless you specify otherwise. Note that parameter values do 
not display in the Variables dialog box until an action has 
assigned the new value. 


Column delimiters display as a single bar (|) and row 
delimiters display as two bars (||). To add a value in a new 
column, press CTRL+TAB and then type the value. To adda 
value in a new row, press CTRL+ENTER and then type the value. 


Use the Global and Local check boxes on the Special Variables 
dialog box to control the creation and display of local and 
global variables in the dialog box. When both Local and 
Global are on, LightShip assumes the variable is local unless 
you type an ampersand as the first character. If only Global is 
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on, LightShip adds an ampersand at the beginning of the 
variable name. If only Local is on, LightShip will remove an 
ampersand from the first character of a variable name. 


cS Hint A quick way to create a multi-cell variable is to create a user- 
entry document object and type a variable reference in it. 
Then go to the Browse level and type the values. Remember to 
press CTRL+TAB between columns and CTRL+ENTER between 
rows. The values you enter are assigned to the variable. 


Creating @ To create a variable: 
Variables 


1. Choose Special Variables. 


A dialog box appears. 


This Drop-Down Box 
Lists All Existing 
Variables 


Figure 10-1 Creating Variables 


2. Type the variable name in the Name text box or click the 
down arrow next to the Name text box and select a name 
from the list. 

3. Press the TAB key or click in the Value text box. 


4. Type the variable value. 


5. To add another variable or edit the one you just entered, 
do not press ENTER. Press SHIFT+TAB to go back to the text 
box on the left. 
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Editing Variables 


Deleting Variables 


1; 


1. 
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When you are finished, choose OK. 


To edit a variable: 

Choose Special Variables. 

The Variables dialog box appears. 

Select the variable. 

It appears in the text boxes at the top of the dialog box. 
Click in the text box you want to change. 

Type the new name or value. 


When you are finished, choose OK. 


To delete a variable: 

Choose Special Variables. 

The Variables dialog box appears. 

Select the variable. 

It appears in the text boxes at the top of the dialog box. 
Choose Delete. 


When you are finished, choose OK. 
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Assigning Values 
with No Action 


Passing 
Parameters 
Between Screens 


Defining 
Parameters 
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Defining and Passing Parameters 


You Can assign new values to variables and pass them to other 
LightShip screens using hotspots and menu objects. You do 
not need to define an action to assign parameters. If there are 
actions associated with the object, values defined on the 
Action Parameters dialog box are assigned immediately before 
the actions are carried out. 


You can also use functions to assign values to variables. For 
example, Copy/Test performs a simple variable assignment and 
MOUSETEXT assigns a document object cell value that you 
click on to a variable. 


To only assign parameter values and perform no other action, 
assign the parameter value(s) on the Action Parameters dialog 
box. 


To pass parameters to other screens, choose any of the Open 
File actions or the Return in Retrace Path action. Then assign 
the parameter value(s) on the Action Parameters dialog box. 


@ To define parameters on the Hotspot or Menu Action 
Parameters dialog box: 


— 


Create or select a hotspot or menu object. 
2. Define the action(s). 
3. Choose Hotspot Parameters or Menu Parameters. 


The Action Parameters dialog box appears for the selected 
object. 
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Hotspot Action Parameters 


Name. Value: 
[2] 


Name = Value List: 


TS To change an 
existing parameter, 


click on it. It ap- 


pears in the text 


name value 


boxes where you 
can edit it. 


Figure 10-2 Defining Hotspot and Menu Parameters 

4. Type the parameter name in the Name text box or click 
the down arrow next to the Name text box and select a 
parameter name from the list. 

5. Press TAB to move to the Value text box. 

6. Type the value. 

7. To type another parameter or edit the name you just en- 
tered, do not press ENTER. Press SHIFT+TAB to go back to 


the Name text box. 


8. When you are finished, choose OK. 


Assigning Values by Pointing 


You can assign a parameter value by pointing to a cell or rows 
and columns in a document. To select data from multiple 
columns, the document object must have Document Layout 
Columns turned on and a column delimiter defined. If you 
select multiple rows and columns without a column delimiter 
defined, LightShip interprets each row as only one cell. For 
information on defining columns, refer to Chapter 4: 
Displaying Data. 
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Assigning a Value § To assign a value by pointing: 
by Pointing 
1. Select a parameter in the list, type a name in the Name 
text box, or click on the down arrow next to the Name 
text box and select a parameter name from the list. 


Hotspot Action Parameters 
Name: Yalue: 


mm i} CT 


Name = Value List: 


Figure 10-3 Defining a Parameter by Pointing 


2. Press TAB or click in the Value box to enable the Point 
button. 


3. Choose Point. 


The screen changes to Point mode, which lets you select 
data. 


4. Drag the mouse over the value(s) you want to assign to 
the parameter. 
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LightShip: Puint to Parameter product 
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Figure 10-4 Pointing to a Value 


5. Choose OK! on the menu bar. 


The Action Parameters dialog box appears again. When 
you point to a value, the parameter box displays the value 


as (Point). 


Hotspot Action Parameters [ox] 
Name: 


8 es 


Name = Value List: 


Figure 10-5 Assigning a Value by Pointing 


6. Choose OK. 
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Deleting @ To delete a parameter assignment: 
Parameters 
1. Choose Hotspot Parameters or Menu Parameters. 
2. Select the parameter. 
It appears in the text boxes at the top of the dialog box. 
3. Choose Delete. 
4. When you are finished, choose OK. 
This deletes the parameter assignment but leaves the 
variable intact. 
@ To delete a variable on the Action Parameters dialog 


box: 


Assign a blank value to the parameter name. 


Referencing Variables 


Whenever you reference a variable, LightShip substitutes the 
reference with the value assigned to the variable. Variable 
substitution, which allows you to build dynamic screens and 
queries, is a key element of a LightShip application. New 
values are substituted only when you execute a hotspot or 
menu object. 


Referencing You can reference variables almost anywhere that you can 
Variables enter text, in text objects, user-entry document objects, or in 
any text box wide enough for four characters. 
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To reference a variable, precede it with an atsign and enclose it 
in parentheses. For example, suppose you are defining keys 
for a query. If you initialize the following variables in the 
Variables dialog box: 


keys = Product | Channel | Region | City 
key = Product 
level = 1 


Wherever you want to substitute the values, you would refer to 
them as: 


@ (keys) 
@ (key) 
@ (level) 


LightShip substitutes: 
Product | Channel | Region | City 


Product 
1 


You can also use indirect and nested references to variables. 
For example, @(key) is an indirect reference to the variable 
key and @(@key)) is a nested reference to the variable key. 
Suppose you have the following values: 


key = Product 
product = Cola 


You can refer to: 

@(key) = @(@(key) ) 

and LightShip evaluates it to: 

Product = Cola 

LightShip evaluates from the inner-most parenthesis outwards. 


On the first pass through, @(key) is equal to "Product." Then 
LightShip evaluates product to equal "Cola." 
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Concatenating Strings 
You can concatenate strings using: 
= & (Concatenate strings) function 


= && (Concat with space) function 
= # Variable references 


Examples of If key=level and number=1 then: 
Concatenate 
Functions temp := key && number 


evaluates temp to "level 1" and 
temp := key & number 
evaluates temp to "level1." 


For more information on & (Concatenate strings)and && 
(Concat with space), see the LighiShip Reference Guide. 


Examples of For example: 
Variable 
References @ (filename) .LSF 


evaluates to a filename with an .LSF extension. 
If key = level and number = 1 then: 
@ (key) @ (number) 


evaluates to "level1." 


10-14 


Chapter 10 Using Variables and Parameters 


If number = 1 and key1 = product then: 
@(key@ (number) ) 


evaluates to "product." 


An Example Using Variables and Parameters 


This example shows a text object that toggles among three 
values. You might want to try it as an exercise. 


We created and initialized three variables in the Variables 
dialog box, shown in Figure 10-6. 


Variables 

Name: 

Name = Value List: 
statel = Prior 


state? = Actual 
state 3 =- Buduet 


Figure 10-6 Initializing Variables 


Then we created a hotspot. We defined parameters with the 
same names as the variables we defined in Figure 10-6. We 
used variable references as values to cause the states of the 
variables to change. 
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Hotspot Action Parameters [ox } 
Name: Value: 
G 


Name = Value List: 
statel = @{state2) „Doete 
state2 = @({state3 | Point... 3 


state 3 = @{statel] 


Figure 10-7 Defining Hotspot Parameters 


The first value of statel is "Prior." Every time we click on the 
hotspot at the Browse level, the value of state1, state2, and 
state3 changes. 


Last, we created a text object that defined the text as @(state1) 
and placed it over the hotspot. 


Text 
@(statel1) 


Figure 10-8 Using a Parameter in a Text Object 


When we go to the Browse level, each time we click on the 
hotspot, it displays one of the values - "Prior," "Actual," or 


State 1 State 2 State 3 


Passing Special 
Characters 
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Passing Parameters from Windows or DOS 


YOu Can pass parameters to a LightShip screen when you start 
LightShip from the DOS command line or the Windows File 
Run command using the following syntax: 


ls <filename> <parameterl> <parameter2>... 
For example: 

\ls\ls \ls\top.lsf "Actual" "Budget" 

You can pass parameters with or without a variable name. If 
you pass a parameter without a variable name, you must 
enclose it in double quotes, as shown above. If you do not 
assign a name on the command line, LightShip assigns the 
names P1, P2, P3, etc. P1 refers to the first parameter on the 


command line, P2 to the second parameter, and so on. 


To assign variable names to values on the command line, use 
the following syntax: 


ls <filename> <name>=<value>... 

For example: 

\ls\ls \ls\top.lsf item=Paper 

When passing parameters from the command line, spaces ( ), 
equal signs (=) that are not used for assigning values, and 
double quotes (") are treated as special characters. To pass 
any of these characters as parameters, you must put them 
inside double quotes. 


For example, to pass the value "Actual Sales," you would type: 


"upActual Salestttr 
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To pass equal signs, you would type: 


equation="a+b=c" 


Example Figure 10-9 shows how the following parameters appear in the 
Variables dialog box: 


"actual" 

"unActual Saleg""n 
item=paper 
equation="a+b=c" 


Variables 
Name: Value: 
E 


Name = Value List: 
equation - aib c 


Rom = paper 
P1 = actual 
P2 = “Actual Sales” 


Figure 10-9 Passing Parameters from the Command Line 
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Running and Testing an Application 


This chapter explains how to use LightShip at the Browse level 
and how to use LightShip’s debugging features. 


ISF press the F4 
key to move Running an Application 


between the 


Browse and Author You run applications at the Browse level. Figure 11-1 shows 
levels. the default Browse-level menu bar. 


Lightship 


Figure 11-1 The Default Browse-Level Screen 


LightShip User’s Guide 


Browse-Level The LightShip Browse-level menu bar contains File, Edit, and 

Menu Bar Special menus. All the commands perform the same way as at 
the Author level, except the Copy command allows you to 
copy the entire screen without selecting it first. 


Menu-bar menu objects that you create at the Author level 
normally appear on the menu bar to the right of the LightShip 
Browse menus, unless Options Hide Menu Bar is on. 


Executing Actions 


You execute actions at the Browse level by choosing a hotspot 
Or menu item. 


The cursor changes to a hand icon by default when you move 
it over a hotspot. You can change the cursor by specifying a 
cursor file for the hotspot. For more information, see Chapter 
8: Creating Hotspots. 


@ To break out of actions that are executing: 


Press the ESC key. 


Typing into User-Edit Documents 


You can type into a user-entry document at the Browse level if 
Document User Edit is turned on for that object. If the 
document contains a variable reference, any value you type in 
is assigned to the variable and displays on the screen. 


When you move the cursor over a user-edit document, the 
cursor changes to an I-beam. When you click in the document 
object, all the text is selected. To overwrite all the text, just 
start typing. To edit the text, click on the insertion point. The 
cursor changes to a flashing vertical bar. To add a new 
column, press CTRL+TAB. To add a new line, press CTRL+ENTER. 


2. 


3. 
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To type in a user-edit document: 
Click in the document. 
Type into the document. 


When you are finished, press ENTER. 


For information on creating user-edit document objects, see 
Chapter 4: Displaying Data. 


Copying to the Clipboard 


You can copy all or part of the screen to the Clipboard at the 
Browse level. 


To copy the entire screen: 

Choose Edit Copy or press CTRL+INS. 

To copy a portion of the screen: 

Drag the mouse over the area you want to copy. 


You see a dotted selection rectangle as you drag the 
mouse. 


Choose Edit Copy or press CTRL+INS. 
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[> Important 


Opening the 
Debug Window 


Testing an Application 


You can use the Debug window to record information while 
running an application. You can list the following information 
at any time: 


Parameter values as they are assigned and referenced 
Actions as they are executed 

Information about objects 

RGB numbers of colors on the palette 


To record information in the Debug window, you must open it 
before running an application. When you list new information 
in the Debug window, existing information displayed in the 
window is not updated. The new information is appended to 
the existing list, up to a fixed amount of lines. You might want 
to clear the window before listing new information. 


@ To open the Debug window: 
Choose Special Debug. 
The screen changes to the LightShip Debug window 


shown in Figure 11-2. The window is blank if you have 
not executed any actions. 


The Menu Bar 
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File Edit Qptions Yiew 
om LightShip Debug 


File Edit Options... Objects List Variables List Palette List 


Figure 11-2 The LightShip Debug Window 


The Debug window has a Control menu and Maximize and 
Minimize boxes. You control the window in the same way that 
you would any window, except that when you close LightShip, 
the Debug window closes with it. When you minimize it, it 
becomes an icon, which you can double-click on to activate. 


The menu bar displays the following menu items: 


The File menu allows you to print the screen and exit 
from the Debug window. 


The Edit menu allows you to copy and clear the screen. 


The Options command lets you control what is displayed 
and the way it is output. 


The Objects List command lists the objects on the screen 
and their attributes. 


The Variables List command lists the current variable 
values. 
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Displaying 
Information in the 
Window 


æ The Palette List command lists the current RGB numbers 
for the colors in the palette. 


Depending on the settings in the Debug Options dialog box, 
parameter values or actions may list automatically in the 
window after you execute actions. For example: 


1. Open the Debug window. 

2. To start with a clear screen, choose Edit Clear. 
3. Switch to a LightShip application screen. 

4. Execute one or more actions. 

5. Switch back to the Debug window again. 


If you have executed actions and have not changed the 
default settings in the Debug Options dialog box, the 
Debug window lists local and global parameter values. 


a= LightShip Debug Me 
File Edit Qptions... Objects List Variables List Palette List 


>: Line2=>0 
line3=>0 

line4=>0 

: LineS=>0 

: Keyl=>Product 

: Product=>Cola 
KkKey2=>Channel 
Channel=>Retail 
KeyS3=>Region 
Region=>Midweet 
level=>1 

lnexti=>2 

level=>1 
key1=>Product 
date=>01/01/89 
level=>1 
criterial=>@(key1) <> “Total” and @(key2) = "Total" 
key1l=>Product 
key2=>Channel 
LINE1<=f a% 


CL 
> oF. 
Gas 
CL 
CL 
cS 
CL : 
cA. 2 
As 
CL: 
CA. 3 
o. 
o L 
CA. 
oR 
CL: 
CL: 
Sr ER 
CA. 
ot i. 


Figure 11-3 Displaying Information in the Window 


Labels 


Copying the 
Window 


Clearing the 
Window 


Closing the 
Window 
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A label on the left side of the screen identifies the information. 


Table 11-1 Debug Window Labels 


To copy the information in the window to the 
Clipboard: 


Choose Edit Copy or press CTRL+INS. 


To clear the Debug window: 

Choose Edit Clear or press SHIFT+DEL. 

To close the Debug window and return to the main 
screen: 

Turn off Debug on the main LightShip screen. 

Or 


Choose Control Close, press ALT+F4, or choose File Exit in 
the Debug window. 
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Setting Debug Window Options 


The Options command on the Debug window allows you to 
specify: 


Number of lines to display in the window 
Whether to list local or global parameters 
Whether to list actions 


Whether to list information in the window or in a file, or 
both 


Setting Debug @ To set Debug window options: 
Window Options 
Choose Options. 


A dialog box appears. 


Debug Options 
Display 


X4 Local Parameters 


[xX] Actions 


Output 
XX] Window. Lines 
C] File 


Figure 11-4 The Debug Options Dialog Box 


Listing When you list information in the window, LightShip lists as 

Information in the many lines as are specified in the Debug Options dialog box. 

Window When LightShip reaches the maximum number of lines 
specified, it erases lines from the top of the list as it adds new 
lines at the end. 
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Writing to a File 


Saving the 
Settings 
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© To list information in the window and control the 


number of lines in the list: 


Leave the Window, Lines check box on to list information 
in the Debug window. 


In the Window, Lines text box, type a number from 50 to 
500 to set the maximum number of lines you want to list 
in the window. 


You can write the information in the Debug window to an 
ASCII text file. The information is written to the file when the 
actions are executed or when you choose Objects List or 
Palette List. You can print the file from the Windows Notepad 
or the DOS command line. 


= 
i. 


To write information to a file: 
Turn on the File check box. 


Type the filename to which you want to write the 
information in the File text box. 


You can optionally add an extension to the filename. 


LightShip does not provide a default extension. 


There are three ways to save the settings in the Debug 
Options dialog box: 


= Turn on Save Prefs. on Exit in the Preferences dialog 
box. 


s Turn on Query Save on Exit in the Preferences dialog 
box and press ENTER when you are prompted to save 


the settings when you exit from LightShip. 


= Turn on Save Settings and choose OK. 
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Tracing Parameter Values 


The parameter list is different from the variable list. The 
variable list shows the current value of all variables. The 
parameters list only displays parameter values after an action 
has occurred, for example, when a new value is assigned or 
when Lightship retrieves a value. A parameter assignment 
statement assigns a value. The symbol, :=, indicates that the 
value was assigned. The symbol, =>, indicates that the value 
was retrieved. 


Local parameters are identified by an LCL label. Global 
parameters are identified by a GBL label. 


@ To list parameter values: 
1. Make sure the Global Parameters and Local Parameters 
check boxes in the Debug Options dialog box are set 


correctly. 


2. Minimize the Debug window or Switch to the LightShip 
application screen window. 


4. Execute one or more actions. 


4. Restore or Switch to the Debug window again. 


Listing Variable Values 
The variable list shows the current value of all variables. 
@ To list the current variable values: 
Choose Variables List. 
The variable values appear next to the variable name and 


an equals sign. The label VAR displays on the left side of 
the window. 
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LightShip Debug 
File Edit Qptions... Objects List Yariables List Palette List 


` queries = Product <> “Total” and Channel = “Total” 
Product = "Cola" and Channel <> "Total" and Region = *Teta.i” 


Product = "Cola" and Channel = “Fountain” and Region <> i i 
>.> “Total” 
Product = "Cola" and Channel = “Fountain” and Region = "Nort 
<> “Total” 
dflage = 1 


cap = City by Cola, Fountain, Northeast 
date = 01/01/90 
tmpkey = Region 
cape = All Producte 
: Channel by Cola 
- Region by Cola, Fountain 
- City by Cola, Fountain, Northeast 
query = Product = "Cola" and Channel = "Fountain" and Rel: 
- $t" and City <> “Total” 


Figure 11-5 Listing Variables 


i 


Tracing Actions 
@ To trace actions: 


1. Make sure the Actions check box in the Debug Options 
dialog box is on. 


2. Minimize the Debug window or Switch to the LightShip 
application screen window. 


3. Execute one or more actions. 

4. Restore or Switch to the Debug window again. 
Variable assignments are listed first, followed by the 
actions that were executed. Each action appears next to 
an ACT label as: 


Executing Actions for Object #n. 


where n is the number of the object. 
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If you have Global Parameters or Local Parameters turned 
on in the Debug Options dialog box, these appear as they 
are assigned or retrieved. 


LightShip Debuy 
File Edit Qptions... Objects List Yariables List Palette List 


xecuting Actions for Object 
- Parameters: 
: 1: Function closeflag :=- 8 
: 2: — File — Replace in Retrace Path, File: TOPINT.LSF 
Executing Menu Action:@&close Itea: 
Parameters: 
= Comment If closeflag LS terminating; close QE/EXCEL if applic 
: else 
>: If not c... 
: 2: Function closeflag = i 
3: If True Begin 
: 13: If End 
: Executing Menu Action:kkopen Iten: 
Paraneters: 
1: Comment Init Closeflag to close QE/EXCEL if open 
2: Function closeflag := i 


Figure 11-6 Listing Actions 


Listing Object Information 


You can list all the objects on the current screen next to the 
label OBJ. Objects list from back to front and are identified 
with a number. The lowest number is the object that is behind 
all other objects and the highest number is the object that is in 
front of all other objects. 


The object type, screen position, and all other attributes 
associated with each object are also listed. The total number 
of objects on the screen appears at the end of the list. 


@ To list information about objects on the current 
screen: 


Choose Objects List. 


11-12 


Selecting an 
Object 
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LightShip Debug 
EHe Edit Options... Objects List Yariables List Palette List 
Parameters: 
Aotione: 
1: Function closeflag := O 
2: Open File - Add to Retrace Path, File: TOPCOM.LSF 
8:27 Pes.:362,.82 Width:286 Height = 132 sno ttetepet 
Text Required:No Highlight:No Gray If Inactive: 
Highlight Type:None 
Cursor file:Default 
Parametere: 
Aotione: 
1: Function closeflag := O 
2: Open File - Add to Retrace Path, File: TOPEXT.LSF 
8:28 Pes.-436.15 Width-154 Weight-19 Type-Nena 
Name:&&callerror Item: Separator:No 
Parametere: 
1: Function closeflag := O 
2: Open File - Add to Retrace Path, File: ERROR.LSF 
8:29 Pos.:223.3 Width-172 Naight:59 Type -Inage 
Source:Clipboard 
Save Palette:No Fit Obj. To Image:Yee Fit Image To Obj .:No 
Scaling - Horizontal:1.00 Vertical:1.00 
8:308 Pes.:362.269 Width:208 HWeight-132 Egpo: Hetspot 
Text Required:No Highlight:No Gray If Inactive: 
Highlight Type:None 
Cureor file:Default 
Parameters: 
Aotione: 
1: Function closeflag := O 
2: Open File - Add to Retrace Path, File: KPARTOP.LSF 
8:31 Pes.:289.1806@ Width:158 Height = 17 Type-Meau 
Name: A&Aclose Item: Separator:No 
Parametere: 
: Comment If cloeeflag LS terminating; cloee GE/EXCEL if applic 


Figure 11-7 Listing Objects 


You can select an object on the LightShip screen by double- 
clicking on the line that identifies the object in the Debug 
window. This line is in bold type next to the lowercase label 
obj. The cursor changes to an up arrow when it is over one of 
these special object lines. 


Listing Palette Numbers 


The Palette List command lists the RGB numbers for all the 
colors on the palette, next to the label PAL. 


@ To list the RGB numbers for the palette: 


Choose Palette List. 
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LightShip Debug 


~ 47 255 
: Total Palette Entries:48 


Figure 11-8 Listing the Palette Numbers 


The first number is the index, or the number of the color 
on the palette. The second number identifies the amount 
of red in the color. The third number identifies the 
amount of green in the color. The last number identifies 
the amount of blue in the color. 


Printing the Debug Window 
@ To print the information in the Debug window: 


Choose File Print. 


Tracking Errors 


LightShip creates an error log file that records any errors that 
occur. The log file has the extension, .LOG, and is named after 
the LightShip executable file. For example, if your executable 
file is called LS.EXE, the log file is named LS.LOG. 


The log file records the date and time that the error occurred, 
the pathname and filename of the file that was running, and 
what the error was. 
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New errors are appended to the end of this file. We 
recommend erasing this file periodically to prevent it from 
becoming too large. 


Types of Errors When an error occurs, LightShip displays a message on the 
screen. There are three types of error messages: 


Warning A warning message provides information; it is 
not as serious as an error. Warning messages 
are always displayed on the screen at both the 
Author and Browse levels, but are only output 
to the error log file at the Browse level. 


Error An error message means that something has 
happened that prevents the program from 
continuing. Error messages often tell you what 
you can do to correct the error. 


Crash A crash message tells you that the application 
has an unrecoverable error and is terminating. 
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Chapter 12 


Using Dynamic Data Exchange 


This chapter describes Microsoft’s Dynamic Data Exchange 
(DDE) protocol and how LightShip uses it to communicate 
with other Windows applications. It also shows examples of 
DDE Requests and DDE Executes. 


What is Dynamic Data Exchange? 


Microsoft Windows Dynamic Data Exchange (DDE) is a 
method that allows applications to communicate with each 
other. The program that initiates communication is the client 
and the program that responds is the server. A communica- 
tion link between a client and a server is called a channel. The 
client controls the channel and requests services from the 
server. 


DDE provides transactions to allow communication between 
a client and server. For example, the Initiate transaction opens 
a channel, the Request transaction gets data, and the Termi- 
nate transaction ends the communication and closes the chan- 
nel. The Advise transaction establishes a hotlink between ap- 
plications, so that data is automatically updated in the client 
whenever it changes in the server. Most applications support 
only a portion of all transactions provided by DDE. 
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Specifying the 
Server 
Application 


Supported 
Transactions 


When you use DDE, you specify the server application and 
data to be exchanged with the following fields: 


x Application 
* Topic 
S Item 


The application is the name of the server application, without 
the .EXE extension. 


The topic identifies a data group or entity you want to access, 
often the name of a window or a filename in the server appli- 
cation. 


The item is a data object that can be passed in a DDE data 
exchange, for example, specific rows and columns of data. 


LightShip and DDE 


LightShip uses DDE to retrieve data from other applications 
and send commands to them. Document objects and image 
objects can retrieve data with DDE and hotspots and menu 
objects can send commands with DDE. 


LightShip can communicate with any Windows application 
that conforms to DDE protocol, including Microsoft Excel, 
Word, PowerPoint®, Pioneer Q +E database editor, Precision 
Software Superbase4®, and Compete! Modeler™. LightShip 
only supports the role of client; it cannot function as a server. 


Besides Initiate, Advise, and Terminate, LightShip supports 
two DDE transactions: 


X Request 
y Execute 


A Request retrieves data from the server and establishes a data 
link. 


Hotlinks 


Number of 
Channels 


Application 
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An Execute sends commands to the server. To see the com- 
mands your server application supports, refer to that applica- 
tion’s documentation. 


LightShip supports DDE hotlinks, which means that once a 
data link is established, the data is updated automatically in 
LightShip whenever it changes in the server. Hotlinks are only 
supported when Special Calculation Automatic is on. 


All DDE communication between applications occurs on a 
channel. You can open up to 20 channels on a LightShip 
screen. 


Syntax for Application and Topic 


The syntax of the Application and Topic fields are the same for 
both DDE Requests and DDE Executes. The application name 
is limited to 32 characters. The topic cannot exceed 255 char- 
acters. On DDE Requests, the item also cannot exceed 255 
characters. If this is a problem, you might be able to request 
data using a DDE Execute if the server application supports a 
DDE Execute command that requests data. For examples, see 
"DDE Executes." 


For information about the syntax for the Item field for a 


Request, see "DDE Requests." For information about the 
syntax for the Item field for an Execute, see "DDE Executes." 


For the application, type the name of the server application 
(without the .EXE extension). For example, for Excel, type: 


excel 
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or for Q+E, type: 


qe 


Topic The topic identifies a data group or entity in the server. It is 
usually a filename or the name of a window in the server ap- 
plication. There is also a special topic called System. The 
System topic is used in different ways, depending on the appli- 
cation; it usually provides a context for items of information 
that might be of general interest to an application. Refer to 
your application’s documentation to see what System items it 


supports. 


Excel Example For Excel, the topic can be System or the name of an open file. 
For example: 
system 
or 
annual.xls 

Q+E Example For Q+E, the topic can be a Query Window Name, a Query 
File Name, a SELECT statement, or System. If you reference a 


.QEF file, Q+E opens the file automatically. For example: 


annual.qgef 


DDE Requests 


Document objects and image objects can perform DDE 
Requests. A DDE Request retrieves data from the server and 
establishes a data link. The link only exists if both applications 
are running and the topic is open. 
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When Data is 
Updated 


Format 


The Paste Link 
Option 
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When Calculation Automatic is on, LightShip updates data 
whenever it changes in the server. LightShip also updates data 
when a screen opens or when a variable reference in a DDE 
Request changes. When Calculation Manual is on and you 
make a literal change in the DDE Request dialog box, 
LightShip prompts you to execute the request. Otherwise, 
when Calculation Manual is on, LightShip only updates DDE 
data when a screen opens or when you issue a Special 
Calculate Now command. 


LightShip can send DDE Requests for text (CF TEXT) and 
bitmap (CF_BITMAP) formats. 


Defining a DDE Request 


To define a DDE Request, create or select a document or 
image object and choose the Document Source or Image 
Source command. When you specify a DDE Request as the 
source for a document or image object, the DDE Data Request 
dialog box opens. 


The syntax of the Request depends on the application. This 
section shows examples from various applications, but you 
must also refer to the documentation of the server application. 


If the server supports the Link format, the Paste Link option on 
the DDE Data Request dialog box is the easiest way to request 
data. It allows you to go to the other application and copy the 
data you want to the Clipboard. When you click the Paste Link 
button on the DDE Data Request dialog box, LightShip fills out 
Application, Topic, and Item on the dialog box for you. For 
more information on using Paste Link, see Chapter 4: Display- 
ing Data. 
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Syntax for the 
Item 


Excel Examples 


Q+E Examples 


The item is a data object that can be passed in a DDE 
transaction. 


To retrieve data from Excel, type any reference or name that is 
recognized by Excel. For example: 


R1C1:R15C15 
or 


the name of a range of cells (defined by the Excel Define 
Group command). 


Q+E most commonly accepts an area specification for the 
item. For example, to get all the data in the Query Window, 


type: 
all 


To get the data from the first to the fifteenth rows, and the first 
to the fifteenth columns, type: 


R1C1:R15C15 


Breaking Out of a DDE Request 


When you send a DDE Request or Execute, if there is no 
response within a certain amount of time, LightShip quits 
looking for a response and displays a message that the Request 
or Execute timed out. If you do not want to wait for LightShip 
to time Out, you can break out of a DDE Request or Execute 
manually. 


@ To break out of a DDE Request or Execute 
immediately: 


Press the ESC key. 


Controlling Time 
Outs 


Using DDE 
Executes 
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LightShip controls the amount of time to wait for a time out 
with the following settings: 


a DDE Short Timeout 
~ DDE Long Timeout 


The DDE Short Timeout, which is set to 10 seconds by default, 


is used for actions that do not require much time, such as DDE 


Requests or Acknowledgments. 


The DDE Long Timeout, which is set to 60 seconds by default, 
is used for actions that require more time, such as sending 
DDE Executes. 


You can change these settings on the View Preferences dialog 
box. LightShip saves the settings in your LS.INI file. For more 
information, see the View Preferences command in the 
LightShip Reference Guide. 


DDE Executes 


A DDE Execute is one of the actions available to hotspots and 
menu objects. A DDE Execute sends commands to the server. 
The server application provides the commands you can send 
as the item in the DDE Execute transaction. 


DDE Executes are most often used for closing windows, send- 
ing information to the server application, or exiting from the 
server application. DDE Execute commands that close win- 
dows or exit from applications are usually triggered by an 
&&Close menu object. It is most efficient to close down an 
application only once when you are completely finished with 
it, rather than open and close it multiple times during a ses- 
sion. 
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Syntax for the 
Item 


Excel Examples 


I Important 


Defining a DDE Execute 


To define a DDE Execute, create or select a hotspot or menu 
object and choose Actions from the object’s menu. Then 
choose DDE Execute from the list of actions. The DDE 
Execute Action dialog box opens. 


The item is a data object that can be passed in a DDE 
transaction. For Excel and Q+E, use a text value of command- 
equivalent macro functions. To see the commands your server 
application supports, refer to that application’s documenta- 
tion. The item in a DDE Execute is always enclosed in brackets 


([]). 


For example, this item instructs Excel to open the file 
c:\excel\annual.xls: 


[open ("c: \excel\annual.xl1s") ] 


Note that when Excel shows two backslashes (\\) or two 
double quotes ("") as part of the Execute syntax, only enter 
one of them (\ or ") in LightShip or you will receive an error 
message. 


The following item sends the number "600" to the cell in row 1 
column 3: 


[formula (600,r1c3) ] 


The Microsoft Excel FORMULA macro function enters the for- 
mula specified by the first argument into the cell specified by 
the second argument. For more information about this and 
other Excel macro functions, see the Microsoft Excel Functions 
and Macros manual. 


Q+E Example 


Q+E Example 
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The following example of an Execute item uses a .QEF file as 
the topic. This item creates records in Q+E by passing 
parameters from LightShip to Q+E: 


[allow.edit (true) ] [[paste.append(’@(h1) ’)] 
[keys (’ {tab}@(h2) {tab}@(h3) {tab}) ’] 
[Close() ] 


The ALLOW.EDIT command allows modification of data in the 
Query Window if it is set to true. The PASTE.APPEND 
command adds new records using values on the Clipboard or 
values passed as parameters. The KEYS command sends one 
or more keys to Q+E to be executed. The Close command 
closes the active window. 


The following example would use System as the topic. This 
item also sends information to Q+E: 


[open(’@(path) store.dbf’, “dbasefile’) ] 
[allow.edit (true) ][select.area 
(’ric1i:r4c2’)][keys(’@(key1) {tab}@(key2) 
{tab}@(key4) ’][close() ] 


The OPEN command opens a Query Window. The first argu- 
ment in this example specifies the file and file type. The 
SELECT.AREA command highlights the area specified by the 
rowcol:rowcol argument that follows it. See the Q +E User’s 
Guide for more information about these and other DDE 
Execute commands. 
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Closing a Server Application 


Executing a DDE Request or Execute starts a server applica- 
tion, but does not close it. 


5 To close the server application: 


Create an &&Close menu object with a DDE Execute 
action to send DDE Close and Quit commands to the 
server. &&Close is an event-driven menu object that exe- 
cutes actions when a screen closes. For more information 
about &&Close, see Chapter 7: Creating Menu Objects. 


Appendix A 


Starting LightShip from .LSF Files 


This appendix describes how to start LightShip from .LSF files. 


Starting LightShip from .LSF Files 


You can edit your WIN.INI file so that you can start LightShip by double- 
clicking on a file with a .LSF extension. 


$s 


2. 


Go to the Windows Program Manager. 

Open the NOTEPAD. 

Choose File Open. 

For the filename, type: 

win.ini 

Choose OK. 

The file WIN.INI opens. 

Page down to the place in the file with the header [Extensions]. 
Add the following line using the correct path: 
lsf=[pathname]\ls.exe ^.lsf 


Choose File Save. 
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9. Choose File Exit. 


10. Exit from Windows and restart it. 


Appendix B 
LS.INI Options 


This appendix describes the settings in LS.INI. 


What Is LS.INI? 


LightShip’s default system settings are saved in a startup file, which is 
stored in your Windows system directory. This file initializes system 
settings when LightShip starts. The startup file is called LS.INI by default. 
However, if you rename your executable file, LightShip uses the 
executable filename with an .INI extension. 


The default system settings are set in different places: in the Preferences 
dialog box; on the View or Special menus; and some are set internally by 
LightShip. Table B-1 shows the source and default value of each system 
setting. 

Changes you make to system settings are saved if you: 

= Choose Save on the Preferences dialog box. 


= Turn on the Save on Exit option in the Preferences dialog box. 


= If you turn on the Query Save on Exit option and then answer Yes in 
response to LightShip’s prompt to save settings. 


Choosing the Save or OK buttons on the Preferences dialog box issues a 
Calculate Now command and completely repaints the screen. 
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LS.INI Options 


There may be different sections in your LS.INI. Section headings are in 
square brackets. The first line of the file is the [LightShip] section 
heading. 


In the table shown below: 


Device means device-dependent 
View means View menu 

Pref means Preferences dialog box 
Spec means Special menu 


Table B-1 LightShip Default Settings 


a 
Left 


Window maximized or not. 


Device Horizontal coordinate of upper-left 
corner of main window. 


Vertical coordinate of upper-left 


corner of main window. 


Status box displayed or not. 


Height of main window. 


Debug window on or off. 


o 
ge 
3 
4 
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Table B-1 LightShip Default Settings (continued) 


AuthorDisabled 


Author level disabled or not. When 
this is on, you cannot go to the 


Author level from the Browse level. 


Increments between horizontal grid 


View GridHorizontal 
View GridVertical 


l 


Vi ShowHotspots 


iew 
View 


View 
View 


lines. 


Increments between vertical grid 


lines. 


Direct Browse Level Painting on or 
off. When on, objects are repainted 
individually at the Browse level, 
which gives the appearance of faster 
performance. 


Hotspots are outlined or not. 


All objects are outlined or not. 


OutlineObjects 


ShowHiddenObjects 


Hidden objects are displayed or not. 


View 
View Disable Formats is on or off. When 
on, formatting is turned off at the 
Author level. 


The startup banner is displayed 
when LightShip starts. 


Pref 
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Table B-1 LightShip Default Settings (continued) 


setting 


Pref 


DDE _ Short TimeOut Time to wait before timing out on 


DDE Requests. 


Time to wait before timing out on 
DDE Executes. 


Save globals or not. 


Prompt to save settings on exit from 
LightShip or not. 


Pref DDE_ Long TimeOut 


Pref SaveGlobals 


k 
D 


Save settings on exit from LightShip 
without prompting or not. 


Special Create new objects from front to 


CreateInBackground 


back instead of from back to front. 


Pref Redraw Repaint screen when moving 
objects or not. Performance is 


faster when this is off. 


Pref PrintAsBitmap When off, prints a screen using 
Windows settings and fonts. When 
on, prints a screen in bitmap 


format. 


When on, creates a backup file. 
Section heading. 


[Toolbox] 


Internal ToolboxLeft 
ToolboxTop Device Vertical coordinate of upper-left 
corner of Toolbox. 


Horizontal coordinate of upper-left 


corner of Toolbox. 
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Table B-1 LightShip Default Settings (continued) 


Section heading. 


StatusLeft Device Horizontal coordinate of upper-left 
corner of Status box. 


Device Vertical coordinate of upper-left 
corner of Status box. 

= 

Device Top of Debug window. 

i Height of Debug window. 


Internal DebugOptions 


DebugLines 50 Number of lines in the Debug 


window. 
DebugMinimized 


g 


; 


This number is the sum of the 
options in the Debug Options 


dialog box - see Table B-2. 


Debug window minimized or not. 
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Table B-2 Debug Option Values 


‘common fa 
seem pe 
were 


Saving Global Variables 

If you turn on Save Globals in the Preferences dialog box, LightShip adds 
a [Globals] section in LS.INI and saves the global variables there. You can 
also type global variables directly into the file, for example: 


&PATH = C:\LS8\;C:\LS\DEMO; 


Index 


&&Close 7-11 — 7-12 
&&Error 7-11, 7-13 
&&Open 7-11 — 7-12 
&&Recalc 7-11, 7-13 


A 

Actions 9-1 — 9-19 
conditional 9-5 — 9-7 

Area chart 6-4, 6-15 — 6-16 


Author level, 1-4 — 1-6, 3-22 — 3-23 


B 
BAK file 2-7, 2-13, B-4 
Bar chart 6-4 — 6-5, 6-10 — 6-13 


BMP file, displaying 5-15, 5-17 — 5-19 


Browse level 
described 3-22, 11-1 — 11-3 
starting LightShip at 1-5 
Buttons, creating 8-4 — 8-7 


C 


Calculate Now action 4-3, 5-16, B-1 


Capture level xiii 
described 3-22 
starting LightShip at 1-5 
Cascading menu 1-8 
Category 
label 6-2, 6-22 — 6-27 
scale 6-27, 6-32 — 6-35 


CF BITMAP format 5-15, 5-20 — 5-21, 


12-5 
CF_ DIB format 5-15, 5-20 


CF TEXT format 4-7, 12-5 
CF PALETTE 5-20 
Chart menu 6-2 
Chart objects 
area 6-4, 6-10, 6-15 — 6-16 
background area 6-2 — 6-3 
bar 6-4 — 6-5, 6-10 — 6-13 
category scale 6-27, 6-32 — 6-35 
labels 6-2, 6-22 — 6-27 
coloring 6-35 — 6-36 
components of 6-2 — 6-4 
creating 6-5 — 6-8 
crosses line 6-2 — 6-3, 6-30 — 6-31 
data series 6-3, 6-5 — 6-9 
fonts 6-37 
horizontal 6-18 — 6-19 
labels 6-2, 6-22 — 6-27 
legend 6-2 — 6-3, 6-19 — 6-20 
line 6-4, 6-10, 6-14 — 6-16 
numeric scale 6-27 — 6-32 
pie 6-4, 6-10, 6-16 — 6-18 
plot area 6-2 — 6-3 
scale 6-27 — 6-35 
title 6-2 — 6-3, 6-21 — 6-22 
tool 3-2 — 33 
types 6-4 
changing, 6-9 — 6-10 
Chart tool 3-2 — 3-3 
Check boxes 1-9 — 1-10, 8-5 
Clearing 
Debug window 11-4, 11-7 
objects 3-18 


LightShip User’s Guide 


Client applications 12-1 — 12-2 
Clipboard 


Bitmap format 5-15, 5-20 — 5-21, 12-5 
image, displaying 5-18, 5-20 
Text format 4-7, 12-5 


Closing 


Debug window, 5-5, 5-7 
LightShip 1-17 

screen 2-14 

server application 12-10 


Close menu object 7-11 — 7-13 
Color palette 


system 5-13 — 5-15 
image object 5-24 — 5-25 


Coloring 


charts 6-35 — 6-36 

pie 6-18 
document objects 4-25 
draw objects 5-12 
format objects 4-45 — 4-48 
image objects 5-24 — 5-25 
screens 2-3 — 2-4 
text objects 5-3 — 5-4 
variances 4-38 — 4-45 


Columns, in document objects 4-16 — 4-19 
Command buttons 1-9 


creating 8-4 


Commands, choosing 1-7 — 1-13 
Concatenating strings 10-14 — 10-15 
Condition flag 9-5 — 9-7 

Control menu 


Debug window 11-5 
LightShip 1-6 


Copying 


actions 9-5 
Browse level 11-3 
objects 3-18 — 3-19 


Create mode 3-22 — 3-23 
Creating objects 3-4 — 3-7 
Cutting objects 3-18 


D 
Data series, chart 6-3, 6-5 — 6-9 
DDE 12-1 — 12-10 
Execute action 7-12, 12-2 — 12-3, 
12-7 — 12-9 
Request 12-1 — 12-6 
breaking out of 12-6 
for bitmap 5-19, 5-21 — 5-23 
for text 4-4, 4-6 — 4-8 
timeout 12-7, B-4 
Debug window 11-4 — 11-7 
actions, listing 11-11 — 11-12 
objects, listing 11-12 — 11-13 
options 11-8 — 11-9, B-5 — BG 
parameters, listing 11-10 
printing 11-9, 11-14 
variables, listing 11-10 — 11-11 
writing to a file 11-9 
Deleting 
chart data 6-9 
objects 3-18 
retrace path entries 2-17 
Destination of a format object 
4-29 — 4-30, 4-37 — 4-39, 4-42 — 48 
Dialog boxes, using 1-9 — 1-13 
Dim if Inactive, for hotspots 8-9 — 8-10 
Directories, changing 2-7 — 2-8 
Document menu 4-2 
Document objects 
coloring 4-25 
columns 4-16 — 4-19 
creating 4-3 — 4-15 
data, anchoring in object 4-24 — 4-25 
described 4-1 — 4-2 
fonts 4-26 — 4-28 
formatting 4-28 — 4-36 
hiding 4-20 
interactive 4-9, 4-12 — 4-15 
layout 4-16 — 4-19 
scrolling 4-20 — 4-24 


Document objects (continued) 

source 4-2, 4-4 

changing 4-15 

updating 4-3 

user entry 4-9 — 4-15 
Document tool 3-2 — 3-3 
DOS PATH command 2-20, 2-22 
Draw menu 5-9 
Draw objects 

see also specific objects 

coloring 5-12 

creating 5-9 — 5-11 

filling 5-12 — 5-13 

outlining 5-12 — 5-13 

types of 5-8 
Draw tools 3-2 — 3-3, 5-9 — 5-10 
Drives, changing 2-7 
Drop-down list box 1-9, 1-11 
Duplicating objects 3-18 — 3-19 
Dynamic Data Exchange see DDE 


E 
Ellipse draw object 5-10 — 5-11 
Erasing objects 3-18 
Error menu object 7-11, 7-13 
Errors, LightShip 11-14 — 11-15 
Event-driven menu objects 
creating 7-10 — 7-13 
described 7-1 — 7-2 
Execute menu 
action 7-1 — 7-3, 7-9 — 7-11, 9-19 
objects 7-2, 7-9 — 7-10 
Exiting 
Debug window 11-7 
LightShip 1-17 
Expressions 9-11 — 9-12 


F 

Files 
LightShip 2-13 — 2-14 
opening 2-14 — 2-16 
saving 2-7 — 2-8 


Index 


Fonts 
chart 6-37 
document object 4-26 — 4-28 
text object 5-4 — 5-5 
Format objects 
changing 4-37 
coloring 4-45 — 4-48 
creating 4-29 — 4-32 
described 4-28 — 4-29 
disabling 4-38 
displaying 4-36 
Format tool 3-2 — 3-3 
Formatting 
document objects 4-28 — 4-36 
numbers 4-32 — 4-35 
Functions 
condition flags 9-5 — 9-6 
defining 9-17 — 9-18 
described 9-10 — 9-12 


G 
Graphics 

drawing 5-8 — 5-11 

in image objects 5-15 — 5-17 
Grid 3-5, 3-17 — 3-18 

chart 6-28 — 6-30, 6-32 — 6-33 
Grouping objects 3-14 


H 
Help 1-16 — 1-17 
Hide 

Menu bar 7-8 


document objects 4-20 
Hotspot menu 8-2 
Hotspot objects 
conditional on text 8-7 — 8-10 
creating 8-2 — 8-7 
cursor 8-11 — 8-13 
described 8-1 — 8-2 
dimming if inactive 8-9 — 8-LO 
displaying 8-7 
Hotspot tool 3-2 — 3-3 
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Image menu 5-16 
Image objects 
creating 5-17 — 5-23 
described 5-15 — 5-16 
resizing 5-25 — 5-27 
updating 5-16 — 5-17 
Image tool 3-2 — 3-3 
Installing LightShip 1-1 — 1-3 


K 


Keyboard, using in a dialog box 1-12 — 1-13 


L 
Labels 
chart 6-22 — 6-27 
Debug window 11-7 
Layout of document objects 4-16 — 4-19 
Legend, chart 6-19 — 6-20 
LightShip 
Browse menus 7-8 — 7-9, 11-2 
compatible software 1-2 
environment variable 2-20 — 2-21 
installing 1-1 — 1-3 
PATH variables 2-20 — 2-21 
quitting 1-17 
starting 1-3 — 1-5 
system requirements 1-1 — 1-2 
Line 
chart 6-14 — 6-15 
draw object 5-10 — 5-11 
Link format 4-7 
List box 1-9, 1-11 
Literals, as function arguments 9-12 — 9-13 
LOG file 2-13, 11-14 — 11-15 
Loops 9-8 — 9-10 
LS.INI file B-1 — B-6 
LSF file 2-12 


M 


Menu menu 7-2 
Menu object 
creating 7-2 — 7-3 
event-driven 7-10 — 7-13 
see also specific objects 
execute 7-9 — 7-10 
menu-bar 7-3 — 7-7 
described 7-1 — 7-2 
displaying objects 7-13 — 7-14 
hiding menu bar 7-9 — 7-10 
Menu tool 3-2 — 3-3 
Messages, error 11-15 
Modes 3-22 — 3-25 
see also specific mode 
Moving 
objects 3-15 — 3-16 
window 1-15 


N 
NA data, displaying 4-49 — 4-50 


Numeric functions 9-10 — 9-11, 9-17 


O 

Objects 
see also specific object 
aligning 3-17 — 3-18 
copying 3-18 — 3-19 
creating 3-4 — 3-7 
cutting 3-18 
described 3-1 
duplicating 3-18 — 3-19 
erasing 3-18 
grouping 3-14 — 3-15 
listing 3-20, 11-12 
moving 3-15 — 3-16 
outlining 3-7 
pasting 3-19 
resizing 3-15 — 3-16 
selecting 3-7 — 3-11 
showing hidden 3-7 


Open 
File actions 2-16 — 2-19 
menu object 7-11 — 7-12 
Opening files 2-14 — 2-16 
Optimize Palette 5-13 
Option buttons 8-5, 8-7 
Options, Debug window 11-8 — 11-9, B-6 
Outline objects 3-7 


p> 
Palette 5-3 
image object, changing 5-24 — 5-25 
system, changing 5-13 — 5-15 
listing RGB numbers, 11-13 — 11-14 
Parameters 
assigning values by pointing 10-9 — 10-11 
creating 10-8 — 10-9 
deleting 10-12 
described 10-1 
passing from Windows 
or DOS 10-16 — 10-18 
tracing values 11-10 
-= Passwords 2-11 — 2-12 
Paste Link 4-7 — 4-8 
PATH variables 2-20 — 2-21 
PCX files, displaying 5-19 
Pie chart 6-16 — 6-18 
Point 
to function arguments 9-13 — 9-16, 9-18 
to variable values 10-9 — 10-11 
Point mode 3-23 — 3-25 
Polygon draw object 5-10 — 5-11 
Preference settings 1-15 — 1-16, B-1 — B-4 
Printing 
Debug window 11-9, 11-14 
screen 2-12 — 2-13 


Q 
Quitting LightShip 1-17 


Index 


R 

Radio buttons 8-5, 8-7 

Recalc menu object 7-11, 7-13 
Rectangle draw objects 5-10 — 5-11 
Retrace path 2-16 — 2-19 


S 
Screens 
see also Window, LightShip 
coloring 2-3 — 2-4 
creating 2-9 — 2-10 
pop-up 2-4 — 2-5 
described 2-2 — 2-3 
printing 2-12 — 2-13 
saving 2-7 — 2-8 
Search path, defining 2-20 — 2-22 
Select mode 3-23 
Selecting 
data in Point mode 3-24 — 3-25 
objects 3-7 — 3-11 
Server application 12-1 
closing 12-10 
Source of a format object 4-38 
defining a separate 4-42 — 4-45 
Starting LightShip 1-3 — 1-5 
Status box 3-21 
String functions 9-9 — 9-10 
Strings 
concatenating 10-14 — 10-15 
in Function Action dialog box 9-12 — 9-13 
in Variables and Parameters dialog boxes 
10-4 


T 
Technical support hotline number 1-3 
Temporary files 2-8, 2-13 — 2-14, 
Testing an application 11-4 — 11-15 
Text box, using 1-9 — 1-11 

Text menu 5-2 
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Text objects 
changing 5-7 — 5-8 
coloring 5-3 — 5-4 
creating 5-2 — 5-3 
fonts 5-4 — 5-5 
shadowed 5-5 — 5-7 
Text Required, for hotspots 8-7 — 8-10 
Text tool 3-2 — 3-3 
Title, chart 6-21 — 6-22 
Tickmarks 
chart category 6-32 — 6-35 
chart numeric 6-29 — 6-30 
TMP file 2-13 — 2-14 
Toolbox 3-3 
Tools 3-2 — 3-3 
Tracing parameter values 11-10 


U 


User-entry document objects 4-9 — 4-14 
User edit, for document objects 4-12 — 2-14 


V 


Variables 
assigning values 10-2 — 10-4 
creating 10-5 — 10-7 


Variables (continued) 
deleting 10-7 
described 10-1 — 10-2 
editing 10-7 
global 10-2, 10-5 
initializing 10-2 — 10-4 
legal values 10-4 — 10-5 
local 10-2 
PATH 2-21 
referencing 10-12 — 10-13 
Variances 
coloring 4-38 — 4-45 
defining in a different source document 
4-42 — 4-45 


W 
Window, LightShip 
see also screens 
caption, adding 2-5 
components of 1-6 
Saving position and size 2-6 
WIN.INI file A-1 


Word wrap, in document objects 4-16 — 4-17 


